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Foreword 



rd , 



This Technical Specification has been produced by the 3 Generation Partnership Project (3GPP). 

The contents of the present document are subject to continuing work within the TSG and may change following formal 
TSG approval. Should the TSG modify the contents of the present document, it will be re-released by the TSG with an 
identifying change of release date and an increase in version number as follows: 

Version x.y.z 

where: 

X the first digit: 

1 presented to TSG for information; 

2 presented to TSG for approval; 

3 or greater indicates TSG approved document under change control. 

y the second digit is incremented for all changes of substance, i.e. technical enhancements, corrections, 
updates, etc. 

z the third digit is incremented when editorial only changes have been incorporated in the document. 
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Scope 



A Subscriber Identity Module Application Programming Interface (SIM API) has been defined in TS 42.019 [4] as a 
technology-independent API by which toolkit applications and (U)SIMs co-operate. That specification is independent 
of the programming language technology used to create the application, the platform used to host the application and 
the runtime environment used to execute the application. 

The present document includes information applicable to (U)SIM toolkit application developers creating applications 
using the C programming language ISO/IEC 9899 [7]. The present document describes an interface between toolkit 
applications written in the C programming language and the (U)SIM in order to realize the co-operation set forth in 
TS 42.019 [4]. In particular, the API described herein provides the service of assembling proactive commands and 
disassembling the responses to these commands for the application programmer. 

Software tools, integrated software development environments and software management systems that may be used to 
create application programs are explicitly out of scope of the present document. 
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3 Definitions and abbreviations 

3.1 Definitions 

For the purposes of the present document, the following terms and definitions apply: 

application: computer program that defines and implements a useful domain-specific functionality 

The term may apply to the functionality itself, to the representation of the functionality in a programming language, or 

to the realization of the functionality as executable code. 

application executable: representation of an application as collection of executable codes 

application program: representation of an apphcation in a programming language such as assembly language, C, Java, 
WML or XHTML 

Application Programming Interface (API): collection of entry points and data structures that an application program 
can access when translated into an application executable 

byte code: processor-independent representation of a basic computer operation such as "increment by one" that is 
executed by computer program called a byte code interpreter 

data structure: memory address that can be accessed by an application executable in order to read or write data 

entry point: memory address that can be branched to by an application executable in order to access functionality 

defined by an application-programming interface 

Depending on the software technology, an entry point is also called a subroutine, a function or a method. 

executable code: generic term for either byte code or native code 

framework: defines a set of Application Programming Interface (API) functions for developing applications and for 
providing system services to those applications 

loadfile: representation of an application executable that is transmitted from the terminal to the smart card operating 

system 

A loadfile typically includes information about the application executable in addition to the application executable 

itself. 

native code: processor-dependent representation of a basic computer operation such as "increment by one" that is 
executed by the hardware circuitry of a computer's central processing unit 

toolkit application: uses the commands described in TS 31.11 1 [2] and TS 11.14 [8] 

3.2 Abbreviations 

For the purpose of the present document, the following abbreviations apply: 

APDU Application Protocol Data Unit 

API Application Programming Interface 

CAT Card Application Toolkit 

CS Circuit Switched 

DCS Digital Cellular System 

DF Dedicated File 

DTMF Dual Tone Multiple Frequency 

EF Elementary File 

ELF Executable and Linkable Format 

FID File Identifier 

GSM Global System for Mobile communications 

ME Mobile Equipment 

NAA Network Access Application (SIM or USIM) 
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OTA 

SIM 

SMS 

STK 

SW 

TAR 

TLV 

TPDU 

UICC 

URL 

USIM 

USSD 



Over The Air 

Subscriber Identity Module 

Short Message Service 

SIM ToolKit 

Status Word 

Toolkit Application Reference 

Tag, Length, Value 

Transport Protocol Data Unit 

(not an acronym) 

Uniform Resource Locator 

Universal Subscriber Identity Module 

Unstructured Supplementary Services Data 



4 Description 

The (U)SIM Application consists of the following: 

APDU handlers for communicating with the ME; 

File system and file access control; 

Toolkit Framework that provides services to Toolkit appUcations. 

The present document describes the C programming language binding for the interface between the (U)SIM application 
and toolkit applications described in TS 42.019 [4]. This API allows application programmers using the C programming 
language to access functions and data described in TS 31.111 [2] and TS 11.14 [8], such that the (U)SIM-based 
applications and the services they implement can be developed and loaded onto ICCs. If required and supported by the 
underlying smart card technology, toolkit applications can be loaded or deleted remotely, after the card has been issued. 



4.1 



Overview 



The 'C -binding for (U)SIM API shall provide function calls for pro-active functions and transport functions. The figure 
below shows the interactions between a typical toolkit application (shown in blue) and the various functional blocks of 
the (U)SIM (shown in orange). The C-bindings for these APIs are presented in subclause 4.2. 
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4.2 Design Rationale and Upward Compatibility 

Some functions on the C SIM API take parameters that correspond to optional TLVs in TS 31.111 [2] and TS 1 1 . 14 [8] . 
If the actual parameter value passed to the function is NULL, the corresponding TLV is not passed to the ME; an 
example of an optional parameter is Catlconldentifier that corresponds to the ICON IDENTIFIER TLV. 

Some proactive commands have a very large number of optional TLVs, such as SETUP CALL. Therefore, this API 
offers two variants that address this aspect, CatSetupCall and CatSetupCallEx. The first function, CatSetupCall, takes 
as parameters everything that is necessary to issue a successful SETUP CALL proactive command (i.e. everything 
required to construct the mandatory TLVs as required by TS 31.111 [2] and TS 11.14 [8]) and also includes optional 
user interface TLVs (title and icon) for ease of use. 

The second function, CatSetupCallEx, takes a parameter block that can be extended in future versions of the present 
specification. The parameter block contains members that correspond to all mandatory and optional TLVs for the 
SETUP CALL proactive command. 

The reason for introducing the "...Ex" variants is threefold: 

Rather than extend the parameter list of a function to take a large number of optional parameters for each call, it 
is preferable to set up the parameters using named structure members before issuing the call to the function. 

If a future version of TS 3 1 . 1 1 1 [2] or TS 1 1 . 14 [8] extends the optional parameters for a proactive command, 
the corresponding parameter block can be extended to encompass these parameters without changing the 
function prototype. 

Any source code written for an older version of this C SIM API can be recompiled with a later version without 
change and will remain upwardly compatible at the source as long as the suggested coding standards are adhered 
to. 



4.3 Application Triggering 



The application-triggering portion of the SIM Toolkit Framework is responsible for the activation of toolkit 
applications, based on the APDU received by the card. 

The ME shall not be adversely affected by the presence of applications on the (U)ICC card. For instance a syntactically 
correct Envelope shall not result in an error status word in case of a failure of an application. The only application as 
seen by the ME is the (U)SIM application. As a result, a toolkit application may return an error, but this error will not 
be sent to the ME. 

The difference between an application and a toolkit application is that a toolkit application does not typically handle 
APDUs directly. It will handle higher-level messages. Furthermore the execution of a function could span over multiple 
APDUs, in particular, the proactive protocol commands. 

All the applications that have registered interest in the event are triggered in order of their priority. 

The current context is switched to the toolkit application. 
- A pending transaction is aborted. 

The current file context of the toolkit application is the MF. 

The current file context of the current selected application is unchanged. 
On termination of a toolkit application execution of CatExit(): 

The context switches back to the context of the current selected application, the NAA application. 

A pending toolkit application transaction is aborted. 
Here after are the events that can trigger a toolkit application: 
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EVENT_PROFILE_DOWNLOAD 

Upon reception of the Terminal Profile command by the (U)SIM, the Toolkit Framework stores the ME profile and then 
triggers the registered toolkit application that may want to change their registry. A toolkit application may not be able to 
issue a proactive command. 

EVENT_MENU_SELECTION,EVENT_MENU_SELECTION_HELP_REQUEST 

A toolkit application might be activated upon selection in the ME's menu by the user, or request help on this specific 
menu. 

In order to allow the user to choose in a menu, the Toolkit Framework shall have previously issued a SET UP MENU 
proactive command. When a toolkit application changes a menu entry of its registry object, the Toolkit Framework shall 
dynamically update the menu stored in the ME during the current card session. The SIM Toolkit Framework shall use 
the data of the EFsume file (TS 51.011 [11] and TS 31.102 [15]) when issuing the SET UP MENU proactive command. 

The positions of the toolkit application menu entries in the item list, the requested item identifiers and the associated 
limits (e.g. maximum length of item text string) are defined at the loading of the toolkit application. 

If at least one toolkit application registers to EVENT_MENU_SELECTION_HELP_REQUEST, the SET UP MENU 
proactive command sent by the Toolkit Framework shall indicate to the ME that help information is available. A toolkit 
application registered for one or more menu entries may be triggered by the event 

EVENT_MENU_SELECTION_HELP_REQUEST, even if it is not registered to this event. A toolkit appUcation 
registered for one or more menu entries should provide help information. 

EVENT_FORMA TTED_SMS_PP_ENV, EVENTJJNFORMA TTED_SMS_PP_ENV, 

EVENT_FORMATTED_SMS_PP_UPD,EVENT_UNFORMATTED_SMS_PP_UPD 

A toolkit application can be activated upon the reception of a short message. There are two ways for a card to receive an 
SMS: via the Envelope SMS-PP Data Download or the UpdateRecord EFsms instruction. 

The reception of the SMS by the toolkit application cannot be guaranteed for the Update Record EFsms instruction. 

The received SMS may be: 

formatted according to TS 23.048 [3] or an other protocol to identify explicitly the toolkit application for which 
the message is sent; 

unformatted or using a toolkit application specific protocol the Toolkit Framework will pass this data to all 
registered toolkit applications. 

EVENT_FORMA TTED_SMS_PP_ENV 

This event is triggered by an envelope APDU containing an SMS_DATADOWNLOAD BER TLV with an 
SMS_TPDU simple TLV according to TS 23.048 [3]. 

The Toolkit Framework shall: 

- verify the TS 23.048 [3] security of the SMS TPDU; 

trigger the toolkit application registered with the corresponding TAR defined at application loading; 

take the optional Application Data posted by the triggered toolkit application if present; 

secure and send the response packet. 

The toolkit application will only be triggered if the TAR is known and the security verified. Application data will also 
be deciphered. 

EVENT_UNFORMATTED_SMS_PP_ENV 

The registered toolkit apphcations will be triggered by this event and get the data transmitted in the APDU envelope 
SMS DATADOWNLOAD. 
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EVENT_FORMATTED_SMS_PP_UPD 

This event is triggered by Update Record EFsms with an SMS TP-UD field formatted according to TS 23.048 [3]. 

The Toolkit Framework shall: 

update the EFsms file with the data received, it is then up to the receiving toolkit application to change the SMS 
stored in the file (i.e. the toolkit application need to have access to the EFsms file); 

- verify the TS 23.048 [3] security of the SMS TPDU; 

convert the Update Record EFsms in a TLV List, an EnvelopeHandler; 

trigger the toolkit application registered with the corresponding TAR defined at application loading. 

EVENT_UNFORMATTED_SMS_PP_UPD 

The SIM Toolkit Framework will first update the EFsms file, convert the received APDU as described above, and then 
trigger all the registered toolkit applications. All of them may modify the content of EFsms (i.e. the toolkit applications 
need to have access to the EFsms file). 

EVENT_UNFORMATTED_SMS_CB 

When the ME receives a new cell broadcast message, the cell broadcast page may be passed to the card using the 
envelope command, e.g. the application may then read the message and extract a meaningful piece of information that 
could be displayed to the user, for instance. 

EVENT_CALL_CONTROL_BY_SIM 

When the NAA is in call control mode and when the user dials a number, this number is passed to the Toolkit 
Framework. Only one toolkit application can handle the answer to this command: call barred, modified or accepted. 

EVENT_EVENT_DOWNLOAD_MT_CALL,EVENT_EVENT_DOWNLOAD_CALL_CONNECTED, 

EVENT_EVENT_DOWNLOAD_CALL_DISCONNECTED,EVENT_EVENT_DOWNLOAD_LOCATION_STATUS, 

EVENT_EVENT_DOWNLOAD_USER_ACTIVITY,EVENT_EVENT_DOWNLOAD_IDLE_SCREEN_AVAILABLE, 

EVENT_EVENT_DOWNLOAD_CARD_READER_STATUS 

The toolkit application will be triggered by the registered event download trigger, upon reception of the corresponding 
Envelope command. In order to allow the toolkit application to be triggered by these events, the Toolkit Framework 
shall have previously issued a SET UP EVENT LIST proactive command. When a toolkit application changes one or 
more of these requested events of its registry, the Toolkit Framework shall dynamically update the event list stored in 
the ME during the current card session. 

EVENT_MO_SHORT_MESSAGE_CONTROL_BY_SIM 

Before sending an SMS MO entered by the user, the SMS is submitted to the Toolkit framework. Only one toolkit 
application can register to this event. 

EVENT_TIMER_EXPIRA TION 

This event is registered when the application executes a successful Toolkit CatGetTimer(). The toolkit application can 
then manage this (these) timer(s), and it will be triggered at the reception of the APDU Envelope TIMER 
EXPIRATION. The Toolkit Framework shall reply busy to this Envelope APDU if it cannot guaranty to trigger the 
corresponding toolkit application. 

EVENT_UNRECOGNIZED_ENVELOPE 

The application registered to this event shall be triggered by the framework if the BER-TLV tag contained in the 
ENVELOPE APDU is not defined in the associated release of TS 31.111 [2] and TS 1 1 . 14 [8] and if no corresponding 
constant is defined in the list of the ToolkitConstants interface. By providing the means to transfer an arbitrary block of 
data, the Unrecognized Envelope Event will allow a toolkit application to handle the evolution of the specifications 
TS 31.111 [2] andTS 11.14 [8]. 
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EVENT_STA TUS_COMMAND 

At reception of a STATUS APDU command, the SIM Toolkit Framework shall trigger the registered toolkit 
application. 

A range of events is reserved for experimental and proprietary usage (from -128 to -1). As the definition of these events 
is not standardized, the use of these events may make the toolkit application behave differently on different platforms. 

The toolkit application shall be triggered for the registered events upon reception, and shall be able to access to the data 
associated to the event using OpenEnvelope() or the low-level functions. 

The order of triggering the toolkit application shall follow the priority level of each toolkit application defined at its 
loading. If several toolkit applications have the same priority level, the last loaded toolkit application takes precedence. 



4.4 Proactive command handling 



The (U)SIM application toolkit protocol (i.e. 91xx, Fetch, Terminal Response) is handled by the network access 
application and the Toolkit Framework. The toolkit application shall not handle those events. 

The network access application and the Toolkit Framework shall handle the transmission of the proactive command to 
the ME, and the reception of the response. The Toolkit Framework will then return in the toolkit application just after 
the proactive command. It shall then provide to the toolkit application the values as indicated in the function 
parameters. It also provides the raw return information so that the toolkit application can analyse the response. 

The proactive command is sent to the ME as defined and constructed by the toolkit library without any check of the 
Toolkit Framework. 

The toolkit application shall not issue the following proactive commands: SET UP MENU, SET UP EVENT LIST, 
POLL INTERVAL, POLLING OFF; as those are system proactive commands that will affect the services of the Toolkit 
Framework. 



4.5 Application Loading 



Applications compliant to the present document are represented for loading as loadfiles in the Executable and Linkable 
Format (ELF) described in Tool Interface Standard (TIS) Executable and Linking Format Specification [9] and 
SYSTEM V Application Binary Interface [10]. The application executable in the ELF loadfile may be either native 
code or byte code that has been created through a process of compiling the representation of the application program in 
the C programming language. 

The e_machine entry in the ELF header is set to according to the table in annex A and indicates the architecture for 
which the application executable in the loadfile has been prepared. 

Coding for other processors, processor instruction set extensions and byte code interpreters will be defined as needed 
processor-specific or interpreter-specific supplements to SYSTEM V Application Binary Interface [10] may also be 
provided as needed. 

Loadfile linkers, loaders and installers, whether on-card or off -card, return an error condition if the application 
representation in the loadfile cannot be accommodated or if resources requested by the application are not available. 

The over-the-air application loading mechanism, protocol and application life cycle are defined in TS 23.028 [3]. 



5 'C'-language binding for (U)SIM API 

5.1 Overview 

This subclause presents the 'C'-language binding to (U)SIM API. It is divided into sections as follows: 
Toolkit application entry and exit. 
Man-Machine Interface. 
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Timers. 

Supplementary card reader. 

UICC file store access. 

- Registry. 
Miscellaneous. 
Low-level functions. 
Network services. 

- Supporting data types. 

For each function, the prototype is given followed by a table describing the parameters and whether they are input [in] 
or output [out] parameters. There is explanatory text which explains the function's purpose and whether it is a proactive 
command or not. 



5.2 Toolkit Application Functions 



Toolkit applications will start by executing the application-defined function main. There are no arguments to main, nor 
are there any return results. The application can find out why it was invoked using the CatGetFrameworkEventt 
function. The Framework events that can cause an application to be invoked can be split into the following groups: 

Command monitoring. 

ME monitor events. 

Application lifecycle change. 

Command monitoring enables applications to be invoked when the framework receives commands from the ME. 
Currently supported commands that can be monitored are: 

TERMINAL PROFILE: monitoring this command enables an application to be invoked when the ME is 
powered on. 

STATUS: monitoring this command enables an application to be invoked when the ME polls for proactive 
commands. 

ENVELOPE: monitoring this command enables the application to be informed of specific envelope type arrival 
for example call control envelopes can be monitored. 

ME monitor events are events that the framework can ask the ME to monitor; for example an event can be sent on call 
connection. ME monitored events are delivered to the application in the EVENT DOWNLOAD envelope as received 
from the ME. 

The application lifecycle event enables the framework to invoke an application when the application status has changed. 
This is mainly to enable an application to be run at installation time so that it can set up its registry entries. The details 
of the application lifecycle events are provided in TS 3L116 [14]. 

5.2.1 main 

void 

main (void) ; 

The main function is the application entry point. The apphcation should not return from main; it must call the CatExit 
function. 

An example main function is given below: 

void main (void) 

{ 

switch {CatGetFrameworkEvent { ) ) 
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case EVENT_APPLICATION_LIFECYCLE_INSTALL : 
// set up registry for this application 

CatSetMenuString{ 

CatNotifyOnEnvelope {SMS_PP_DOWNLOAD_TAG, 1) 
CatNotifyOnEvent {CARD_READER_STATUS, 1) ; 
break ; 

case EVENT ENVELOPE COMMAND: 



{ 



BYTE length, - 

switch {CatOpenEnvelope (Stlength) ) 

{ 

case MENU_SELECTION_TAG: 

// search for help request 

break; 
case SMS_PP_DOWNLOAD_TAG : 

break ; 
case EVENT_DOWNLOAD_TAG : 

// search for card reader status event 

break; 
default: 

CatExit { ) ; 



break; 
default: 

CatExit {) ; 
break; 



CatExit {) ; 



5.2.2 CatGetFrameworkEvent 

CatFrameworkEventType 
CatGetFrameworkEvent (void) ; 



RETURN 



Framework event type that caused the application to run; see 
CatFrameworkEventType for details. 



5.2.3 CatExit 

void 

CatExit (void) ; 



CatExit causes the application to terminate execution and return control to the framework. When the application is 
restarted, it enters at main. 
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5.3 Registry 



The menu entry(ies) of the application, together with the set of framework events that the appUcation is interested in, 
may be registered using the functions defined in this subclause. 

5.3.1 CatSetMenuString 

void 

CatSetMenuString (BYTE MenuID, 

BYTE MenuStringLength, const void *MenuString, 

const Catlconldentif ier * Iconldentifier, 

BYTE HelpAvailable, 

BYTE NextAction) ; 



MenuID 


[in] 


The menu ID by which this entry is l<nown. 


MenuStringLength 


[in] 


The length, in bytes, of IVIenuString. 

The menu entry to be placed in the registry. If MenuString is NULL or 


MenuString 


[in] 


IVIenuStringLength is zero, any existing menu entry associated with IVIenulD 

is removed and is not displayed by the ME. 

Optional icon identifier; see Catlconldentifier for member details. If 


Iconldentifier 


[in] 


Iconldentifier is NULL or if Iconldentifier.Uselcon is zero, no icon identifier is 
sent to the ME. 


HelpAvailable 


[in] 


If non zero the application can supply help. 


NextAction 


[in] 


The (optional) next action value 



CatSetMenuString allows the application to define a menu entry together with an icon. A non-zero value can be 
supplied if a next action indicator is required. This function will implicitly request that the application is notified of 
menu selection envelopes i.e. there is no requirement to call the CatNotifiyOnEnvelope function. An application can 
have several menu entries and must examine the menu selection envelope to decide which menu selection caused it to 
be invoked. 

The ordering of menu entries within a menu presented by the ME is based on increasing integer values of identifiers 
selected by the application. Note that any application's menu item ordering may be further overridden by an external 
source, e.g. card issuer, via a request to the SIM Toolkit framework this mechanism is beyond the scope of the present 
document. 

5.3.2 CatNotifyOnFrameworkEvent 

void 

CatNotifyOnFrameworkEvent (CatFrameworkEventType Event, BYTE Enabled); 



^ . r. 1 A framework event the application is interested in, see 

^ ^ CatFrameworkEventType for details. 

If non-zero the framework event is monitored otherwise the framework event 
isn't monitored. By default only application lifecycle events are monitored. 



Enabled [in] 



CatNotifyOnFrameworkEvent enables the application to add/remove a framework event to/from the set of framework 
events that it is interested in. 
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5.3.3 CatNotifyOnEnvelope 

void 

CatNotifyOnEnvelope (CatEnvelopeTagType Tag, BYTE Enabled); 



T- r. 1 The particular envelope type to monitor; see CatEnvelopeTagType for 

'^^ ^'"J details. 

Enahlpd V 1 '^ non-zero the envelope type is monitored otherwise the envelope type isn't 

^ ^ monitored. 



CatNotifyOnEnvelope enables the application to add/remove an envelope monitoring event to/from the set of the 
envelope monitoring events it is interested in. Note that the monitoring of MENU SELECTION, TIMER EXPIRATION 
and EVENT DOWNLOAD envelopes is handled by the framework. 

5.3.4 CatNotifyOnEvent 

void 

CatNotifyOnEvent (CatEventType EventType, BYTE Enabled); 



EventType [in] The particular event type to monitor; see CatEventType for details. 
Enabled [in] If non-zero the event type is monitored otherwise the event isn't monitored. 



CatNotifyOnEvent enables the application to add/remove an ME monitored event to/from the set of ME monitored 
events it is interested in. 

5.4 Man-Machine Interface 
5.4.1 CatAddltem 

void 

CatAddltem (BYTE ItemTextLength, const void *ItemText, BYTE Itemldentifier) ; 



ItemTextLength 


[in] 


The length in bytes of the following /femTexf field. 


ItemText 


[in] 


Text associated with item. 

Specifies a unique identifier to be associated with this selection. This value is 


Itemldentifier 


[in] 


returned in the Selectedltem parameter of CatSelectltem if this item is 
selected from the menu. 



CatAddltem adds an item to a list for the user to select. See CatSelectltem below for details on the construction of a 
display list. 

5.4.2 CatSelectltem 

void 

CatSelectltem (BYTE TitleLength, const void *Title, 
CatSelectltemOptions Options) ; 



TitleLength [in] The length in bytes of Title. 

Title [in] Title of the list of choices. 

Options [in] Acceptable values for this parameter are listed in CatSelectltemOptions. 



CatSelectltem initiates the construction of a list of items to be displayed to the user and from which the user is expected 
to select exactly one entry. After CatSelectltem has been called, entries are added to the list one at a time using the 
CatAddltem entry point above. When all items have been added to the list, the list is sent to the ME using the 
CatEndSelectltem entry point below. CatEndSelectltem causes the list to be displayed and returns to the caller the item 
selected. 
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5.4.3 CatEndSelectltem 

CatGeneralResult 

CatEndSelectltem (BYTE *SelectedItem, 

const Catlconldentif ier * Iconldentifier) , 



Selectedltem 
Iconldentifier 
RETURN 



[out] Index of item selected by user. 

Optional icon identifier; see Catlconldentifier for member details. If 
[in] Iconldentifier is NULL or if Iconldentifier. Uselcon is zero, no icon identifier is 

sent to the IVIE. 
The GeneralResult code of the SELECT ITEM proactive command. 



CatEndSelectltem issues the proactive command SELECT ITEM that displays on the ME a list of items for the user to 
choose from. The terminal response is parsed and if successful the Selectedltem parameter is set to the index of the item 
chosen. See CatSelectltem above for details on the construction of a display list. 

5.4.4 CatDisplayText 

CatGeneralResult 

CatDisplayText (CatDCSValue TextDCS, BYTE TextLength, const void *Text, 

CatDisplayTextOptions TextOptions, 

CatTextFormat TextFormat, 

CatForegroundColor ForegroundColour, 

CatBackgroundColour BackgroundColour, 

const Catlconldentifier * Iconldentifier , 

BYTE ImmediateResponse) ; 



TextDCS 


[in 


TextLengtti 

Text 

TextOptions 

TextFormat 

ForegroundColour 

BackgroundColour 


[in 
[in 
[in 
[in 
[in 
[in 


Iconldentifier 


[in 


ImmediateResponse 


[in 


RETURN 





The data coding scheme for Text. Acceptable values for this parameter are 

listed in CatDCSValue . 

The length in bytes of Text. 

String to display on ME. 

Acceptable values for this parameter are listed in CatDisplayTextOptions . 

Format of text; e.g. bold, italic, etc. 

Foreground colour of text; i.e. colour of the letters. 

Background colour of text; i.e. colour filled in behind the letters. 

Optional icon identifier; see Catlconldentifier for member details. If 

Icon Identifier \s NULL or if Iconldentifier. Uselcon is zero, no icon identifier 

is sent to the ME. 

True-program continues execution as soon as ME receives instruction. 

False-program waits until text is cleared on the ME before continuing, and 

the Immediate Response TLV is not passed to the ME. 

The GeneralResult code of the DISPLAY TEXT proactive command. 



5.4.5 CatGetlnKey 



CatGeneralResult 

CatGetlnKey (CatDCSValue TitleDCS, BYTE TitleLength, const void *Title, 

CatGetlnKeyOptions Options, 

const Catlconldentifier * Iconldentifier , 

CatDCSValue *DCSOut, void *KeyOut) ; 



TitleDCS 

TitleLength 

Title 

Options 

Iconldentifier 



DcsOut 

KeyOut 
RETURN 



[inj 

[in] 
[in] 
[in] 

[in] 



[out] 
[out] 



The data-coding scheme for Title. Acceptable values for this parameter are 

listed in CatDCSValue . 

The length in bytes of Title. 

String to display on ME. 

Acceptable values for this parameter are listed in CatGetlnKeyOptions . 

Optional icon identifier; see Catlconldentifier for member details. If 

Icon Identifier \s NULL or if Iconldentifier Uselcon is zero, no icon identifier is 

sent to the ME. 

The packing type of the returned key. This parameter is set to one of the 

values listed in CatDCSValue . 

The key pressed. 

The GeneralResult code of the GET INKEY proactive command. 



ETSI 



3GPP TS 31.131 version 11.0.0 Release 11 



19 



ETSI TS 131 131 V1 1.0.0 (2012-11) 



CatGetlnKey issues the proactive command GET INKEY. The terminal response is parsed and if successful the 
DCSOut and KeyOut parameters are updated. 

5.4.6 CatGetlnput 

CatGeneralResult 

CatGetlnput (CatDCSValue TitleDCS, BYTE TitleLength, const void *Title, 

CatGetlnputOptions Options, 

CatDCSValue DefaultReplyDCS , 

BYTE DefaultReplyLength, const void *DefaultReply, 

BYTE MinimumResponseLength, 

BYTE MaximumResponseLength, 

const Catlconldentif ier * Iconldentifier, 

CatDCSValue *MsgOutDCS, BYTE * MsgOutLength, void *MsgOut) ; 



TitleDCS 


[in] 


TitleLength 
Title 


[in] 
[in] 


Options 


[in] 


DefaultReplyDCS 


[in] 


DefaultReplyLength 


[in] 


DefaultReply 


[in] 


MinimumResponseLength 
MaximumResponseLength 


[in] 
[in] 


Iconldentifier 


[in] 


MsgOutDCS 


[out] 


MsgOutLength 

MsgOut 

RETURN 


[out] 
[out] 



The data-coding sclieme for Title. Acceptable values for this parameter are 

listed in CatDCSValue . 

The length in bytes of Title. 

String to display on ME while waiting for the user to press a key. 

Acceptable values for this parameter are listed in CatGetlnputOptions . 

The data-coding scheme for DefaultReply. Acceptable values for this 

parameter are listed in CatDCSValue . 

The length in bytes of DefaultReply. 

Default response string; use NULL for "no reply"-no Default Reply tag 

length value (TLV) is sent to the IVIE. 

Minimum allowed length for the response, in either characters or digits. 

Maximum allowed length for the response, in either characters or digits. 

Optional icon identifier; see Catlconldentifier for member details. If 

Icon Identifier \s NULL or if Iconldentifier Uselcon is zero, no icon identifier 

is sent to the ME. 

Packing type of the returned data. This parameter is set to one of the 

values listed in CatDCSValue . 

Length of the returned message in bytes. 

A pointer to where the returned string or message is placed. 

The GeneralResult code of the GET INPUT proactive command. 



CatGetlnput issues the proactive command GET INPUT. The terminal response is parsed and if successful 
MsgOutDCS, MsgOutLength, MsgOut parameters are updated. 

5.4.7 CatSetupldleModeText 

CatGeneralResult 

CatSetupldleModeText (CatDCSValue TextDCS, BYTE TextLength, const void *Text, 
const Catlconldentifier * Iconldentifier) ; 



TextDCS 



[in] 



TextLength 
Text 


[in] 
[in] 


Iconldentifier 


[in] 



The data-coding scheme for Text. Acceptable values for this parameter are 

listed in CatDCSValue . 

The length in bytes of Text 

String to display while ME is idle. 

Optional icon identifier; see Catlconldentifier for member details. If 

Icon Identifier \s NULL or if Iconldentifier Uselcon is zero, no icon identifier is 

sent to the ME. 

The GeneralResult code of the SETUP IDLE MODE TEXT proactive 

command. 



CatSetupldleModeText issues the proactive command SET UP IDLE MODE TEXT that sets the ME's default text 
string. 
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5.4.8 CatPlayTone 



CatGeneralResult 

CatPlayTone (BYTE TextLength, const void *Text, 
CatTone Tone, 

CatTimeUnit Units, BYTE Duration, 
const Catlconldentif ier * Iconldentifier) 



TextLength [in] The length in bytes of the string 7exf to display on the IVIE. 

Text [in] String to display on ME while sound is being played. 

Specifies tone to play. Acceptable values for this parameter are listed in 

CatTone. 



Tone [in] 

Units [in] 



Unit of time specified for duration parameter. Acceptable values for this 

parameter are listed in CatTimeUnit . 
Duration [in] Amount of time to play the tone, in units specified in the Units parameter 

Optional icon identifier; see Catlconldentifier for member details. If 
Iconldentifier [in] Icon Identifier \s NULL or if Iconldentifier Uselcon is zero, no icon identifier is 

sent to the ME. 
RETURN The GeneralResult code of the PLAY TONE proactive command. 



CatPlayTone issues the proactive command PLAY TONE. 

5.5 Timers 
5.5.1 CatGetTimer 



BYTE 

CatGetTimer (void) ; 



RETURN The identifier of the timer. 



CatGetTimer returns the ID of a timer that is not currently in use. If no timer is available, this function returns zero. 
Timer identifiers are assigned by the framework. 



5.5.2 CatFreeTimer 

void 

CatFreeTimer (BYTE TimerlD) ; 



TimerlD [in] ID of timer to free; obtained from CatGetTimer. 



CatFreeTimer frees the handle to the specified timer, making it available for the next request. It is not a proactive 
command. No information is passed to the ME by this function. 

5.5.3 CatStartTimer 

void 

CatStartTimer (BYTE TimerlD, CatTimerValue *TimerValue) ; 



TimerlD [in] ID of the timer to initialize; obtained from CatGetTimer . 

_. ,, , .. , Initial value of the timer. The value is specified in a structure of type 

TimerVaue [in] ^ .-^. ., , '^ '^ 

"■ ^ CatTimerValue . 

RETURN The GeneralResult code of the TIMER MANAGEMENT proactive command. 



CatStartTimer issues a proactive TIMER MANAGEMENT command to initialize a timer to the parameter values. 
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5.5.4 CatGetTimerValue 

void 

CatGetTimerValue (BYTE TimerlD, CatTimerValue *TimerValue) ; 



TimerlD [in] ID of tlie timer from which to obtain values; obtained from CatGetTimer 

^. ,, , , , The time remaining to run of timer r/mer/D. The value is returned in a 

TimerValue out] , , , , r^ .-r- m , 

' ' structure of type CatTimerValue . 

RETURN The GeneralResult code of the TIMER MANAGEMENT proactive command. 



CatGetTimerValue issues a proactive TIMER MANAGEMENT command to obtain the timer's current value. 

5.6 Supplementary Card Reader Management 

These functions access the supplementary card-reader on a dual-slot ME. 

5.6.1 CatPowerOnCard 

CatGeneralResult 

CatPowerOnCard (CatDevice DevicelD, BYTE *ATRLength, void *ATR) ; 



. The device to power on. An acceptable value for this parameter is a card 

^ reader device selected from CatDevice . 

Size of the ATR buffer on input and the umber of bytes returned by the card 
y lin ou J gg ^i^g ^-ppj ^^ output. 

/A7"f? [out] Pointer to where answer to reset (ATR) will be stored. 

RETURN The GeneralResult code of the POWER ON CARD proactive command. 



CatPowerOnCard issues the proactive command POWER ON CARD that powers on a supplementary card reader. The 
terminal response is parsed and if successful the ATR and ATRLength parameters are. 

5.6.2 CatPowerOffCard 

CatGeneralResult 

CatPowerOffCard (CatDevice DevicelD) ; 



The device to power off. An acceptable value for this parameter is a card 
^ ' reader device selected from CatDevice . 

RETURN The GeneralResult code of the POWER OFF CARD proactive command. 



CatPowerOffCard issues the proactive command POWER OFF CARD that turns off the supplementary card reader. 
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5.6.3 CatPerformCardAPDU 

CatGeneralResult 

CatPerformCardAPDU (CatDevice DevicelD, 

BYTE CAPDULength , const void *CAPDn, 

BYTE * RAPDULength , void *RAPDU) ; 



DevicelD 


[in] 


CAPDU 


[in] 


CAPDULength 


[in] 


RAPDU 


[out] 


RAPDULength 


[out] 


RETURN 





Tlie device to send the command APDU (C-APDU) to. An acceptable value 
for this parameter is a card reader device selected from CatDevice . 
Pointer to the command C-APDU to be sent to the additional card 

device. 

The number of bytes in the C-APDU. 

Pointer to the buffer that will contain the response APDU (R-APDU) returned 

by the card in the additional card reader. You must allocate enough space to 

hold the R-APDU sent by the card. 

The number of bytes returned by the card in the additional card reader. 

The GeneralResult code of the PERFORM CARD APDU proactive 

command. 



CatPerformCardAPDU issues the proactive command PERFORM CARD APDU that sends appUcation program data 
units (APDU) to the supplementary card reader. The terminal response is parsed and if successful the RAPDU and 
RAPDULength parameters are updated. 

5.6.4 CatGetReaderStatus 

CatGeneralResult 

CatGetReaderStatus (CatDevice DevicelD, CatReaderStatusOptions Options, 

BYTE *Status) ; 



DevicelD [in 

Options [in 



Device to detect status of. An acceptable value for this parameter is a card reader 
device selected from CatDevice. 



Selects what type of status information to return. An acceptable value for this 
parameter is selected from CatGetReaderStatusOptions . 

Status [out] Status of additional card reader. 

RETURN The GeneralResult code of the GET READER STATUS proactive command. 



CatGetReaderStatus issues the proactive command GET READER STATUS that retrieves the status of the additional 
card readers on the ME. The terminal response is parsed and if successful the Status parameter is updated. 

5.7 UICC File Store Access 

The abstract type FID is used to denote the file and a set of pre-processor macros are defined that enumerate all of the 
standard files of a NAA file store. A FID could be implemented as an unsigned 16-bit number as follows: 

typedef unsigned short FID; 
#define FID_MF 0x3 FOO 

The starting file-context of a Toolkit application is the MF. When a Toolkit application exits, the file-context is lost. 

The Access Control privileges of the application are granted during installation according to the level of trust. When an 
application requests access to UICC or operator specific files, the Toolkit Framework checks if this access is allowed by 
examination of the file control information stored on the card. If access is granted the Toolkit Framework will process 
the access request, if access is not granted, an appropriate status word will be returned. 

Contents and coding of the file(s) containing access control information are defined in 3GPP TS 31.101 [16]. 

All UICC functions return the status bytes according to 3GPP TS 31.101 [16], where 90 00 represents success. 
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5.7.1 CatSelect 



UINT16 

CatSelect (CatFID Fileldentifier, CatFileStatus *Status) , 



Fileldentifier [in] The file to select. 

Qfgf iig r f. Useful information about the directory or file if it is successfully 

selected. 
The returned 16-bit unsigned value is a concatenation of the SW 
RETURN response bytes with SW1 as the high byte and SW2 as the low byte, so 

a successful execution would return 0x9000. 



CatSelect selects the specified file as the current working file. 

5.7.2 CatStatus 

UINT16 

CatStatus (CatFileStatus *Status) ; 



NumBytes [out] The number of bytes written. 

Status [out] The status of the currently selected file. 

The returned 16-bit unsigned value is a concatenation of the SW 
RETURN response bytes with SW1 as the high byte and SW2 as the low byte, so 

a successful execution would return 0x9000. 



CatStatus returns the file status of the currently selected file as specified in 3GPP TS 31.101 [16]. 

5.7.3 CatGetCHVStatus 

void 

CatGetCHVStatus (BYTE CHVStatus [4] ) ; 



CHV^tatw^ r ti Updates the CHVStatus array With the statusof CHV1 , CHV2, 

^°^ ^ UNBL0CKCHV1 , and UNBL0CKCHV2 with CHV1 at array element zero. 



CatGetCHVStatus returns the current CHV status values. The format of the returned bytes is specified in 3GPP TS 
31.101 [16]. 

5.7.4 CatReadBinary 

UINT16 

CatReadBinary (DWORD Offset, 

DWORD *NumBytes, 

void *Buffer) ; 



Offset 


[in] 


NumBytes 


[in/out] 


Buffer 


[out] 


RETURN 





The offset into the file. 

The number of bytes to be read on input and the actual number read on 

output 

The buffer into which the data is written. 

The returned 16-bit unsigned value is a concatenation of the SW 

response bytes with SW1 as the high byte and SW2 as the low byte, so 

a successful execution would return 0x9000. 



CatReadBinary reads NumBytes from position Offset in the currently selected file into Buffer. 
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5.7.5 CatUpdateBinary 

UINT16 

CatUpdateBinary (DWORD Offset, 

DWORD NumBytes, 
const void *Buffer) , 



Offset 


[in] 


The offset into the file. 


NumBytes 


[in] 


The number of bytes to write. 


Buffer 


[in] 


The buffer containing the data to write to the file. 
The returned 16-bit unsigned value is a concatenation of the SW 


RETURN 




response bytes with SW1 as the high byte and SW2 as the low byte, so 
a successful execution would return 0x9000. 



CatUpdateBinary writes NumBytes contained in Buffer to position Offset in the currently selected file. 

5.7.6 CatReadRecord 

UINT16 

CatReadRecord (DWORD RecordNumber , 

CatRecordAccessMode Mode, 

DWORD Offset, DWORD * NumBytes, 

void *Buffer) ; 



RecordNumber 


[in] 


Mode 


[in] 


Offset 


[in] 


NumBytes 


[in/out] 


Buffer 


[out] 


RETURN 





The record number from which to read when Mode is ABSOLUTE or 

otherwise. 

Indication of wliich record is to be read; viz. NEXT, PREVIOUS, CURRENT 

or ABSOLUTE. 

The offset into the record. 

The number of bytes to be read from the record on input and the number of 

bytes actually read on output 

The buffer into which the data is read. 

The returned 16-bit unsigned value is a concatenation of the SW 

response bytes with SW1 as the high byte and SW2 as the low byte, so 

a successful execution would return 0x9000. 



CatReadRecord reads NumBytes from the record RecordNumber of the currently selected file into Buffer. 

5.7.7 CatUpdateRecord 

UINT16 

CatUpdateRecord (DWORD RecordNumber , 

CatRecordAccessMode Mode, 

DWORD Offset, DWORD NumBytes, 

const void *Buffer) ; 



RecordNumber 


[in] 


The record number to which to write when Mode is ABSOLUTE or 

otherwise 


l\/lode 


[in] 


Indication of which record is to be read; viz. NEXT, PREVIOUS, CURRENT 
or ABSOLUTE. 


Offset 


[in] 


The offset into the record. 


NumBytes 


[in] 


The number of bytes to write into the record. 


Buffer 


[out] 


The buffer containing the data to write to the record. 
The returned 16-bit unsigned value is a concatenation of the SW 


RETURN 




response bytes with SW1 as the high byte and SW2 as the low byte, so 
a successful execution would return 0x9000. 



CatUpdateRecord writes NumBytes into the record RecordNumber of the currently selected file from Buffer. 
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5.7.8 CatSearch 



UINT16 

CatSearch (CatSearchModes Mode, 

DWORD Offset, DWORD PatternLength, 

const void *Pattern) ; 







Defines the seek method, One of 






SEEK FROM BEGINNING FORWARD, 


Mode 


[in] 


SEEK FROM END BACKWARD, 

SEEK FROM NEXT FORWARD, 

SEEK FROM PREVIOUS BACKWARD 


Offset 


[in] 


The offset into the record at which to being pattern matching. 


PatternLengtti 


[in] 


The size in bytes of the pattern to search for. 


Pattern 


[in] 


The buffer containing the pattern to search for. 
The returned 16-bit unsigned value is a concatenation of the SW 


RETURN 




response bytes with SW1 as the high byte and SW2 as the low byte, so 
a successful execution would return 0x9000. 



CatSearch searches records in the currently selected file starting at Offset for the pattern of length PatternLength 
contained in Pattern. If the pattern is found the current record is set appropriately. 

5.7.9 Catlncrease 

UINT16 

Catlncrease (DWORD Increment, 
DWORD *Value) ; 



Increment 


[in] 


The value to increase by. 


Value 


[out] 


The new value. 
The returned 16-bit unsigned value is a concatenation of the SW 


RETURN 




response bytes with SW1 as the high byte and SW2 as the low byte, so 
a successful execution would return 0x9000. 



Catlncrease adds Increment to the current record of the selected cylic file and returns the new Value. The most 
significant byte of Increment is ignored. 

5.7.10 Catlnvalidate 

UINT16 

Catlnvalidate (void) ; 



The returned 16-bit unsigned value is a concatenation of the SW 
RETURN response bytes with SW1 as the high byte and SW2 as the low byte, so 

a successful execution would return 0x9000. 



Catlnvalidate invalidates the selected file. 



5.7.11 CatRehabilitate 

UINT16 

CatRehabilitate (void) ; 



The returned 16-bit unsigned value is a concatenation of the SW 
RETURN response bytes with SW1 as the high byte and SW2 as the low byte, so 

a successful execution would return 0x9000. 



CatRehabilitate rehabilitates the selected file. 
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5.8 Miscellaneous 
5.8.1 CatGetTerminalProfile 

void 

CatGetTerminalProfile (BYTE *ProfileOutLength, BYTE *Profile) ; 



ProfileOutLength [out] The number of bytes written to Profile. 

Profile [out] Tine address at wJiicii tlie terminal profile is written. 



CatGetTerminalProfile returns the stored terminal profile in Profile. 

5.8.2 CatMoreTlme 

CatGeneralResult 
CatMoreTime (void) ; 



I RETURN The GeneralResult code of the MORE TIME proactive command. \ 

CatMoreTime issues the proactive command MORE TIME to the ME that it needs more time to process an application. 



5.8.3 CatPollingOff 

CatGeneralResult 
CatPollingOff (void) ; 



I RETURN The GeneralResult code of the POLLING OFF proactive command. \ 

CatPollingOff issues the proactive command POLLING OFF that disables proactive polling; this essentially turns off 
Ca tPo llln te rva I . 

5.8.4 CatPolllnterval 

CatGeneralResult 

CatPolllnterval (CatTimeUnit Unit, BYTE Interval, 

CatTimelnterval *ActualIntervalOut) ; 



Unit 


[in] 


Interval 


[in] 


RETURN 





Desired time interval. Acceptable values for this parameter are listed in 
CatTimeUnit . 
Interval in units. 

Response from ME negotiating the interval. This may or may not be the 
same as L/n/f and Interval. The value returned is in a structure of type 
CatTimelnterval . 
The GeneralResult code of the POLL INTERVAL proactive command. 



CatPolllnterval issues the proactive command POLL INTERVAL that requests the ME to set a time interval between 
status application program data units (APDU) that the ME sends to the UICC. The ME responds with a time interval of 
its own that most closely matches the application programming interface (API) request. 

Polling can be disabled by using CatPollingOff. 
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5.8.5 CatRefresh 

CatGeneralResult 

CatRefresh (CatRef reshOptions Options) ; 

CatGeneralResult 

CatRefreshWithFileList (CatRefreshOptions Options, 

BYTE FileListLength, 

const void *FileList) ; 



^ Informs the ME of what needs refreshing. Acceptable values for this 

^ '°"^ ^'"^ parameter are listed in CatRefreshOptions . 
FileListLength [in] The length, /nbyfes, of F/7e/-/sf. 
FiieList [in] The file identifiers of the files that have changed. 
RETURN The GeneralResult code of the REFRESH proactive command. 



CatRefresh issues the proactive command REFRESH that informs ME that the NAA has changed configuration due to 
UICC activity (such as an application running). 

5.8.6 CatLanguageNotification 

void 

CatLanguageNotification (CatLanguageNotif icationOptions Options, 

const void * Language) ; 



Options [in] 

Language [in] 

RETURN 



Language options. An acceptable value for this parameter is a card reader 
device selected from CatLanguageNotif icationOptions . 

The 2-character language code as defined by ISO 639 [5], encoded 
using SIVIS default 7-bit coded alphabet as defined by TS 23.038 [6]. 
The GeneralResult code of the LANGUAGE NOTIFICATION proactive 

command. 



CatLanguageNotification issues the proactive command LANGUAGE NOTIFICATION that notifies the ME about the 
language currently used for any text string within proactive commands or envelope command responses. 

5.8.7 CatLaunchBrowser 

CatGeneralResult 

CatLaunchBrowser (CatLaunchBrowserOptions Options, 

BYTE TitleLength, const void *Title, 

BYTE URLLength, const void *URL, 

const Catlconldentif ier * Iconldentifier) ; 



Options [in] 



Options used to launch the browser. Acceptable values for this parameter 

are listed in CatLaunchBrowserOptions . 
TitleLength [in] The length in bytes of the string Title 

Title [in] String to display on the IVIE during the user confirmation phase. 

URLLength [in] The length in bytes of URL. 

URL [in] The URL to open the browser at. 

Optional icon identifier; see Catlconldentifier for member details. If 
Iconldentifier [in] Iconldentifier is NULL or if Iconldentifier. Uselcon is zero, no icon identifier 

is sent to the IVIE. 

The GeneralResult code of the LAUNCH BROWSER proactive 

command. 



RETURN 



CatLaunchBrowser and CatLaunchBrowserEx issue the proactive command LAUNCH BROWSER that launches a 
browser on the ME. 

CatGeneralResult 

CatLaunchBrowserEx (const CatLaunchBrowserExParams *parains) ; 
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The structure CatLaunchBrowserExParams has the following members: 

typedef struct 

{ 

// Mandatory fields 

CatLaunchBrowserOptions Options, 

BYTE URLLength; 

const void *URL; 

// Optional fields 

BYTE BrowserldentityLength; 

const void *BrowserIdentity; 

BYTE BearerLength; 

const BYTE *Bearer; 

BYTE NumProvisioningFileRef erences ; 

BYTE *ProvisioningFileRef erenceLengths ; 

const BYTE **ProvisioningFileRef erences; 

BYTE GatewayProxyldLength; 

const void * GatewayProxyld; 

CatAlphaString Title; 

Catlconldentif ier Iconldentif ier; 
} CatLaunchBrowerExParams; 

with the following members: 



URLLength 

URL 

Bro wserlden tity Length 

Browserldentity 

BearerLength 

Bearer 

NumProvisioningFileReferences 
ProvisioningFileReferenceLengths 
ProvisioningFileReferences 
GatewayProxyldLength 

GatewayProxyld 

Title 

Iconldentifier 



The length in bytes of URL. 
The URL to open the browser at. 
Length in bytes of Browserldentity. 
The browser identity. If Browserldentity is NULL, no BROWSER 

IDENTITY TL V is sent to the ME. 
Length in bytes of Bearer 

The list of bearers in order of priority requested. The type CatBearer 
defines the values acceptable. If Bearer \s NULL, no BEARER TLV is 
sent to the ME. 

The number of Provisioning File References. 
A pointer to the array of Provisioning File References lengths. 
A pointer to the array of Provisioning File References. 
Length in bytes of GatewayProxyld. 

The gateway or proxy identity. If GatewayProxyld is NULL, no TEXT 
STRING TLV describing the gateway/proxy is sent to the IVIE. 
String to display on the ME; see CatAlphaString . 
Optional icon identifier; see Catlconldentifier for member details. If 
Iconldentifier. Uselcon is zero, no icon identifier is sent to the ME. 



5.9 



Low-level Interface 



This subclause presents a low-level programming interface that allows you to: 

Construct proactive commands and send them to the ME. 

Access the terminal response from the ME. 

Search the terminal response and contents of envelopes for specified TLVs. 

Unpack the contents of envelopes from the ME and send responses. 

These functions are provided so that functionality that is not provided in the high level API is still accessible. All of 
these functions work on a single data buffer that has a single data pointer and can only be accessed sequentially. The 
high-level proactive functions may make use of the data buffer so consequently the high-level proactive functions 
should not be used whilst using the low-level functions. 

5.9.1 CatResetBuffer 

void 

CatResetBuffer (void) ; 

This function resets the data pointer to the beginning of the buffer. 
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5.9.2 CatStartProactiveCommand 

void 

CatStartProactiveCommand (BYTE Command, 

BYTE Options, 
BYTE To) ; 



Command [in] Command byte of proactive command. 
Options [in] Command options of proactive command. 
To [in] The destination device identity. 



CatStartProactiveCommand resets the data pointer and starts the construction of a proactive command by writing the 
command tag, command details and device identities to the data buffer. The data pointer is left pointing after the device 
identities so that proactive command specific data can be written. 

5.9.3 CatSendProactiveCommand 

CatGeneralResult 
CatSendProactiveCommand (BYTE *Length) ; 



Lengtii [out] Pointer tliat is updated with the length of the terminal response 
RETURN The general result byte of the terminal response 



CatSendProactiveCommand sends the contents of the data buffer as a proactive command and updates the data buffer 
with the terminal response. The general result byte of the terminal response is returned by this function. The length of 
the terminal response is written to *Length. The data pointer is set to point to the additional information of the terminal 
response. 



5.9.4 CatOpenEnvelope 

CatEnvelopeTagType 
CatOpenEnvelope (BYTE * Length) : 



Lengtii [out] Pointer that is updated with the length of the envelope 
RETURN The envelope tag 



CatOpenEnvelope returns the envelope tag of the data buffer and the length of the envelope data. The data pointer is set 
to point to the envelope data. 

5.9.5 CatSendEnvelopeResponse 

void 

CatSendEnvelopeResponse (void) ; 

CatSendEnvelopeResponse sends the contents of the data buffer as a successful envelope response. 

5.9.6 CatSendEnvelopeErrorResponse 

void 

CatSendEnvelopeErrorResponse (void) ; 

This function sends the contents of the data buffer as an unsuccessful envelope response. 

5.9.7 CatPutData 

void 

CatPutData (BYTE Length, 

const void *Data) ; 
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Length [in] Length of Data 

Data in Pointer to Data 



CatPutData appends Length bytes of data to the data buffer. 

5.9.8 CatPutByte 



void 

CatPutByte (BYTE Data) ; 



Data I'm] Data byte. 



CatPutByte appends the supplied data byte to the data buffer. 



5.9.9 CatPutTLV 

void 

CatPutTLV (BYTE Tag, 

BYTE Length, 

const void * Value) ; 



Tag [in] Tag byte. 

Length [in] Length of value. 

Value [in] A pointer to the value. 



CatPutTLV appends a general TLV to the data buffer. 



5.9.10 CatPutBytePref ixedTLV 

void 

CatPutBytePrefixedTLV (BYTE Tag, 

BYTE Prefix, 
BYTE Length, 
const void * Value) ; 



Tag 


[in] 


Tag byte. 


Prefix 


[in] 


Prefix byte. 


Length 


[in] 


Length of value. 


Value 


[in] 


A pointer to the value. 



CatPutBytePrefixedTLV appends a TLV to the data buffer with a single byte placed before the Value. 

5.9.11 CatPutOneByteTLV 

void 

CatPutOneByteTLV (BYTE Tag, 

BYTE Value) ; 



Tag [in] Tag byte. 
Value [in] Value byte. 



CatPutOneByteTLV appends a single byte valued TLV to the data buffer. 

5.9.12 CatPutTwoByteTLV 

void 

CatPutTwoByteTLV (BYTE Tag, 

BYTE Valuel, 

BYTE Valued) ; 
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Tag [in] Tag byte. 

Valuel [in] First Value byte. 

Value2 [in] Second Value byte. 



CatPutTwoByteTLV appends a two byte valued TLV to the data buffer. 

5.9.13 CatGetByte 



BYTE 

CatGetByte (void) ; 



RETURN Data byte. 



CatGetByte returns the byte at the current data pointer and increments the data pointer by one. 



5.9.14 CatGetData 

const void * 

CatGetData (BYTE Length) ; 



Lengtfi [in] Length of Data 

RETURN Pointer to Data. 



CatGetData returns the current data pointer and increments the data pointer by Length bytes. 

5.9.15 CatFindNthTLV 

const void * 

CatFindNthTLV (BYTE Tag, 

BYTE Occurrence, 

BYTE *Length) ; 



Tag 


[in] 


Tag to find. 


Occurrence 


[in] 


Occurrence of Tag to find with "1 " being the first. 


Lengtfi 


[out] 


Length of found TLV. 


RETURN 




Pointer to data of found TLV 



CatFindNthTLV finds the nth TLV that matches Tag in the data buffer, where nth is specified by the Occurrence 
parameter. If a match is found the data pointer is updated to the found TLV, the function returns a pointer to the found 
value and updates Length with the data length. If no match was found the function returns the null pointer and the data 
pointer is left unchanged. 

5.9.16 CatFindNthTLVInUserBuffer 

const void * 

CatFindNthTLVInUserBuffer (BYTE BufferLen, 

const void *Buffer, 

BYTE Tag, 

BYTE Occurrence, 

BYTE *Length) ; 



BufferLen 

Buffer 

Tag 

Occurrence 

Lengtfi 

RETURN 


[in] 
[in] 
[in] 
[in] 
[out] 


Length of buffer 
Buffer to search 
Tag to find. 

Occurrence of Tag to find with "1 " being the first. 
Length of found TLV. 
Pointer to data of found TLV 
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CatFindNthTLVInUserBujfer finds the nth TLV that matches Tag is the supphed buffer. The function returns a pointer 
to the found value and updates Length with the data length. If no match was found the function returns the null pointer. 

5.10 Network Services 
5.10.1 CatGetLocationlnformation 

CatGeneralResult 

CatGetLocationlnformation (CatLocationlnformation *LocationInformation) ; 



,.,,,. . ,, A pointer to where the location information from the ME is placed. Refer to 

Location nformation [out] .,. /^ .i n < .■ x- ^ ,.-,.■, 

^ ' the CatLocal I nformation section for member details. 

o^T-, ,o. , The GeneralResult code of the PROVIDE LOCAL INFORMATION proactive 

command. 

The GeneralResult code of the DISPLAY TEXT proactive command. 



CatProvideLocationlnfonnation requests the ME to send location information to the (U)SIM using the PROVIDE 
LOCAL INFORMATION proactive command. 

5.10.2 CatGetTiming Advance 

CatGeneralResult 

CatGetTimingAdvance (CatTimingAdvance * TimingAdvance) ; 



... r ti ^ pointer to where the timing advance information from the ME is placed. 

iming vance [ou j Refer to the CatTimingAdvance section for member details. 

RETURN ^^^ GeneralResult code of the PROVIDE LOCAL INFORMATION proactive 

command. 



CatProvideTimingAdvance requests the ME to send timing advance information to the (U)SIM using the PROVIDE 
LOCAL INFORMATION proactive command. 

5.10.3 CatGetlMEl 

CatGeneralResult 
CatGetlMEl (BYTE IMEI[8]); 



IMEI [out] A pointer to where the IMEI of the ME is placed. 

o^T-, ,□. , The GeneralResult code of the PROVIDE LOCAL INFORMATION proactive 

riC I UriN , 

command. 



CatGetlMEl requests the ME to send the IMEI to the (U)SIM using the PROVIDE LOCAL INFORMATION proactive 
command. 

5.1 0.4 CatGetNetworkMeasurementResults 

CatGeneralResult 

CatGetNetworkMeasurementResults (BYTE MeasurementJJesuIts [10] ) ; 



MeasurementResults [out] A pointer to where the network measurement results from the ME is placed, 

□^-r, ,□. , The GeneralResult code of the PROVIDE LOCAL INFORMATION proactive 

command. 



CatGetNetworkMeasurementResults requests the ME to send the network measurement results to the (U)SIM using the 
PROVIDE LOCAL INFORMATION proactive command. 
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5.10.5 CatGetDateTimeAndTimeZone 

CatGeneralResult 

CatGetDateTimeAndTimeZone (BYTE DateTimeAndTimeZone [7] ) ; 



Date TimeAndTimeZone 
RETURN 



[out] A pointer to where the date, time, and time zone from the ME is placed. 

The GeneralResult code of the PROVIDE LOCAL INFORMATION proactive 
command. 



CatGetDateTimeAndTimeZones requests the ME to send the date, time, and time zone information to the (U)SIM using 
the PROVIDE LOCAL INFORMATION proactive command. 

5.10.6 CatGetLanguage 

CatGeneralResult 

CatGetLanguage (BYTE Language [2] ) ; 



Date TimeAndTimeZone 
RETURN 



[out] A pointer to where the language from the ME is placed. 

The GeneralResult code of the PROVIDE LOCAL INFORMATION proactive 
command. 



CatGetLanguage requests the ME to send the language information to the (U)SIM using the PROVIDE LOCAL 
INFORMATION proactive command. 



5.10.7 CatSetupCall 



CatGeneralResult 

CatSetupCall (BYTE CallSetupMessageLength, const void *CallSetupMessage, 
CatTypeOfNumberAndNumberingPlanldentif ier TONandNPI, 
BYTE DiallingNumberLength, const void *DiallingNumber, 
CatSetupCallOptions Options, 

const Catlconldentif ier *UserConfirmationIconIdentifier, 
BYTE CallSetupMessageLength, const void *CallSetupMessage, 
const Catlconldentif ier *CallSeupIconIdentifier) ; 



UserConfirmationMessageLength [in] 

UserConfirmationMessage [in] 

TONandNPI [in] 

DialiingNumberLengtti [in] 

DiaiingNumber [in] 

Options [in] 

UserConfirmationlconldentifier [in] 

CallSetupMessageLength [in] 

CallSetupMessage [in] 

CallSetuplconldentifier [in] 

RETURN 



Length in bytes of UserConfirmationMessage. 

Message to display for user confirmation or NULL. 

Acceptable values for this parameter are listed in 

CatTvpeOfNumberAn(JNumberinqPlanl(Jentifier . 

Length in bytes of DiallingNumber 

Number to call is coded as binary-coded decimal. 

Acceptable values for this parameter are listed in 

CatSetupCallOptions . 

Optional icon identifier to use during the user confirmation phase; see 

CatlconlcJentifier for member details. If 

UserConfirmationlconldentifier is NULL or if 

UserConfirmationlconldentifier.Uselcon is zero, no user confirmation 

phase icon identifier is sent to the ME. 

Length in bytes of CallSetupMessage. 

Message to display for call set up or NULL. 

Optional icon identifier to use during the call setup phase; see 

CatlconlcJentifier for member details. If CallSetuplconldentifier is 

NULL or if CallSetuplconldentifier.Uselcon is zero, no call setup phase 

icon identifier is sent to the ME. 

The GeneralResult code of the SET UP CALL proactive command. 



CatSetupCall and CatSetupCallEx issue the SET UP CALL proactive command to the ME. 
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CatGeneralResult 

CatSetupCallEx (const CatSetupCallExParams *Params) ; 

The type CatSetupCallExParams is defined as follows: 

typedef struct 

{ 

// Mandatory fields 

CatSetupCallOptions Options ; 

CatTypeOfNumberAndNumberingPlanldentif ier TONandNPI ; 

BYTE DiallingNumberLength; 

const void *DialingNumber; 

// Optional fields 

CatAlphaString UserConf irmationMessage; 

BYTE CapabilityConf igParamsLength; 

const void *CapabilityConf igParams; 

BYTE CalledPartySubaddressLength; 

const void *CalledPartySubaddress; 

CatTimelnterval RedialMaximumDuration; 

CatlconOption UserConf irmationi con, - 

CatAlphaString CallSetupMessage; 

CatlconOptions CallSetupIcon; 
} CatSetupCallExParams; 

With the following members: 



Options 

TONandNPI 

DiallingNumberLength 
DialingNumber 

UserConfirmationMessage 

Capability ConfigParamsLength 
Capability ConfigParams 
CalledPartySubaddressLength 
CalledPartySubaddress 

RedialMaximumDuration 



UserConfirmationlcon 

CallSetupMessage 
CallSetupIcon 



Acceptable values for this parameter are listed in CatSetupCallOptions . 
Acceptable values for this parameter are listed in 
CatTypeOfNumberAndNumberingPlanldentifier . 
Length in bytes of DlallingNumber 
Number to call is coded as binary-coded decimal. 
String to display during the user confirmation phase; see CatAlphaString . 
If this parameter is null, no user confirmation message TLV is passed to 
the ME. 

Length In bytes of CapabilityConfigParams. 

A pointer to the capability configuration parameters as coded for EFccp. 
Length in bytes of CalledPartySubaddress. 
The called party subaddress. 

An optional maximum duration for the redial mechanism. If the timelnterval 

member of this structure is zero, no duration TLV is sent to the ME. 

The icon to display during the user confirmation phase. If the 

Uselcon member of this structure is zero, no user confirmation icon 

TLV is sent to the ME. 

String to display during the call set up phase; see CatAlphaString . 

The icon to display during the call setup phase. 



Optional parameters are specifically chosen to use an all-zero binary representation. This means that it is simple to set 
up only the required members of the SetupCallExParams structure by zeroing the whole structure using memset, filling 
in the required members, and sending the result to CatSetupCallEx. As all optional parameters use a zero binary 
representation, the memset serves to initialise them all to the "not present" status. 



5.10.8 CatSendShortMessage 



CatGeneralResult 

CatSendShortMessage (BYTE TitleLength, const void * Title, 

CatTypeOfNumberAndNumberingPlanldentif ier TONandNPI, 
BYTE AddressLength, const void *Address, 
BYTE SmsTPDULength, const void *SmsTPDU, 
CatSendShortMessageOptions Options, 
const Catlconldentif ier * Icon Identifier) ; 
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TitleLength 
Title 


[in] 
[in] 


TONandNPI 


[in] 


AddressLength 
Address 

SmsTPDULength 
SmTPDU 


[in] 
[in] 
[in] 
[in] 


Options 


[in] 


Icon Identifier 


[in] 


RETURN 





Length in bytes of Title. 

String to display wliile IVIE is sending a message. 

Acceptable values for this parameter are listed in 

CatTvpeOfNumberAndNumberinqPlanldentifier . 

Length in bytes of Address. 

Address of the service center where message is being sent. 

Length in bytes of SmsTPDU. 

Formatted short message service (SIVIS) message to send. 

Specifies who packs the message. Acceptable values for this parameter are 

listed in CatSendShortlVlessageOptions . 

Optional icon identifier; see Catlconldentifier for member details. If 

Iconldentifier is NULL or if Iconldentifier.Uselcon is zero, no icon identifier is 

sent to the ME. 

The GeneralResult code of the SEND SHORT IVIESSAGE proactive 

command. 



CatSendShortMessage issues the SEND SHORT MESSAGE proactive command. 

5.10.9 CatSendSS 

CatGeneralResult 

CatSendSS (BYTE TitleLength, const void * Title, 

CatTypeOfNumberAndNumberingPlanldentif ier TONandNPI, 
BYTE SSStringLength, const void *SSString, 
const Catlconldentifier * Iconldentifier) ; 



TitleLength 


[in] 


Length in bytes of Title. 


Title 


[in] 


String to display while ME is sending a message. 


TONandNPI 


[in] 


Acceptable values for this parameter are listed 
CatTvpeOfNumberAndNumberinqPlanldentifier. 


SSStringLength 


[in] 


Length in bytes of SSString. 


SSString 


[in] 


SS string to ME. 

Optional icon identifier; see Catlconldentifier for member details. If 


Iconldentifier 


[in] 


Iconldentifier is NULL or if Iconldentifier.Uselcon is zero, no icon identifier is 
sent to the ME. 


RETURN 




The GeneralResult code of the SEND SS proactive command. 



CatSendSS issues the SEND SS proactive command to the ME. 

5.10.10 CatSendUSSD 

CatGeneralResult 

CatSendUSSD (BYTE TitleLength, const void * Title, 

CatDCSValue MessageDCS, BYTE MessageLength, const void *Message, 
CatDCSValue *MsgOutDCS, BYTE *MsgOutLength, void *MsgOut, 
const Catlconldentifier * Iconldentifier) ; 



TitleLength 


[in] 


The length in bytes of Title. 


Title 


[in] 


String to display while ME is sending a message. 


MessageDCS 


[in] 


The data-coding scheme for Message. Acceptable values for this parameter 
are listed in CatDCSValue. 


MessageLength 


[in] 


The length in bytes of Message. 


Message 


[in] 


Message to send. 


MsgOutDCS 


[out] 


Identifies type of DCS for ttie returned message. 


MsgOutLength 


[out] 


Length of the returned message in bytes. 


MsgOut 


[out] 


Returned string or message. 

Optional icon identifier; see Catlconldentifier for member details. If 


Iconldentifier 


[in] 


Iconldentifier is NULL or if Iconldentifier.Uselcon is zero, no icon identifier is 
sent to the ME. 


RETURN 




The GeneralResult code of the SEND USSD proactive command. 
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CatSendUSSD issues the SEND USSD proactive command. The terminal response is parsed and if successful the 
MsgOutDCS, MsgOutLength and MsgOut parameters are updated. 

5.10.11 CatOpenCSChannel 

CatGeneralResult 

CatOpenCSChannel (CatOpenChannelOptions Options, 

BYTE UserConfirmationLength, const void *UserConfirmation, 

const Catlconldentif ier *UserConfimationIconIdentifier, 

CatTypeOfNumberAndNmnberingPlanldentif ier TONandNPI, 

BYTE DiallingNumberLength, const void *DiallingNumber, 

BYTE BearerDescription [3] , 

UINT16 *BufferSize, 

CatDevice * Channelldentifier) ; 



Options [in] 

UserConfirmationLength [in] 

UserConfirmation [in] 



UserConfirmationlconldentifier [i n] 



TONandNPI [in] 

DialiingNumberLengtli [in] 

DialingNumber [in] 

BearerDescription [in/out] 



BufferSize [in/out] 

Clianneiidentifier [out] 

RETURN 



Acceptable values for this parameter are listed in 

CatOpenChannelOptions . 

Length in bytes of UserConfirmation. 

String to display when ME alerts user that channel is to be opened. 

Optional icon identifier to use during the user confirmation phase; see 

Catlconldentifier for member details. If 

UserConfirmationlconldentifier is NULL or if 

UserConfirmationlconldentifier.Uselcon is zero, no user confirmation 

phase icon identifier is sent to the ME. 

Acceptable values for this parameter are listed in 

CatTypeOfNumberAndNumberinqPlanldentifier . 

Length in bytes of DialiingNumber. 

Number to call is coded as binary-coded decimal. 

Initially contains the bearer description parameters (data rate, bearer 

service and connection element) and is modified to the actual bearer 

description as allocated by the ME. 

Initially contains the desired buffer size and is modified to the actual 

buffer size as allocated by the ME. 

The channel identifier that has been allocated by the ME. 

The GeneralResult code of the OPEN CHANNEL proactive 

command. 



CatGeneralResult 

CatOpenCSChannelEx (const CatOpenCSChannelExParams *Params, 
CatDevice * Channelldentifier , 
BYTE BearerDescription [3] , 
UINT16 *BufferSize) ; 



Params 
Clianneiidentifier 

BearerDescription 

BufferSize 

RETURN 



[in] 
[out] 

[out] 

[out] 



Constant parameter set as defined below. 

The channel identifier that has been allocated by the ME. 

An array to which the actual bearer description allocated by the ME 

will be written. 

The actual buffer size allocated by the ME. 

The GeneralResult code of the OPEN CHANNEL proactive 

command. 



CatOpenCSChannel and CatOpenCSChannelEx issue the proactive command OPEN CHANNEL related to a CS 
bearer. The terminal response is parsed and if the command was successful the BearerDescription, BufferSize and 
Channelldentifier parameters are updated. 

The type CatOpenCSChannelExParams is defined as follows: 

typedef struct 

{ 

// Mandatory fields 

CatOpenChannelOptions Options; 

BYTE AddressLength; 

const BYTE *Address; 

BYTE BearerDescription [3] ; 

UINT16 BufferSize; 

// Optional fields 

CatAlphaString UserConf irmationMessage; 
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Catlconldentif ier UserConf irmationlconldentif ier; 
BYTE SubAddressLength; 
const BYTE *SubAddress; 
BYTE DurationlDef ined; 
CatTimelnterval Durationl; 
BYTE Duration2Def ined; 
CatTimelnterval Duration2; 
CatAddressType LocalAddress; 
CatTextString UserLogin; 
CatTextString UserPassword; 

CAT_MEInterfaceTransportLevelType CAT_MEInterf aceTransportLevel; 
CatAddressType DataDestinationAddress ; 
} CatOpenCSChannelExParams; 

With the following members: 



Options 

AddressLength 
Address 

BearerDescription 

BufferSize 



UserConfirmationMessage 



UserConfirmationlconldentifier 

SubAddressLength 

SubAddress 

Duration 1 Defined 

Durationl 

Duration2Defined 

Duration2 

LocalAddress 

UserLogin 

UserPassword 

CA T_MEInterfaceTransportLevel 

DataDestinationAddress 



Acceptable values for this parameter are listed in 
CatOpenChannelOptions . This field is mandatory. 
Length in bytes of Address. This field is mandatory. 

rA7e address to call. This field Is mandatory. 
The desired bearer parameters (data rate, bearer service and 
connection element). This field Is mandatory. 
The desired buffer size. This field is mandatory. 

String to display during the user confirmation phase; see CatAlphaStrinq . 
If this parameter is null, no user confirmation message TLV is passed to 
the IVIE. If UserConfirmationlVlessage is not null but 
UserConfirmationMessageLength is zero, a user confirmation message 
TLV is passed to the ME with the length component set to zero. 

The Icon to display during the user confirmation phase. If the 
Uselcon member of this structure Is zero, no user confirmation Icon 
TLV Is sent to the ME. 
Length in bytes of SubAddress. 
The subaddress to call. 
Set to nonzero if Durationl is defined. 

Duration of reconnect tries; see CatTimelnterval . 

Set to nonzero If Duratlon2 Is defined. 

Duration of timeout; see CatTimelnterval . 

The LocalAddress; see CatAddressTvpe . 

The user login string. 

The user password string. 

See CAT MEInterfaceTransportLevelType . 

The DataDestinationAddress; see CatAddressType. 



5.10.12 CatOpenGPRSChannel 



CatGeneralResult 

CatOpenGPRSChannel (CatOpenChannelOptions Options, 

BYTE UserConf IrmationLength, const void *UserConfirmation, 

const Catlconldentif ier *UserConf irmationlconldentif ier, 

BYTE BearerDescription [8] , 

UINT16 *BufferSize, 

CatDevice *ChannelIdentifier) ; 
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Options [in] 

UserConfirmationLength [in] 

UserConfirmation [in] 



UserConfirmationlconldentifier [i n] 

BearerDeschption [in/out] 

BufferSize [in/out] 

Channelldentifier [out] 
RETURN 



Acceptable values for this parameter are listed in 

CatOpenChannelOptions . 

Length in bytes of UserConfirmation. 

String to display when ME alerts user that channel is to be opened. 

Optional icon identifier to use during the user confirmation phase; see 

Catlconldentifier for member details. If 

UserConfirmationlconldentifier \s NULL or if 

UserConfirmationlconldentifier.Use\cor\ is zero, no user confirmation 

phase icon identifier is sent to the ME. 

Initially contains the bearer description and is modified to the actual 

bearer description as allocated by the ME. 

Initially contains the desired buffer size and is modified to the actual 

buffer size as allocated by the ME. 

The channel identifier that has been allocated by the ME. 

The GeneralResult code of the OPEN CHANNEL proactive 

command. 



CatGeneralResult 

CatOpenGPRSChannelEx (const CatOpenGPRSChannelExParams *Params, 
CatDevice * Channelldentifier, 
BYTE ActualBearerDescription [8] , 
UINT16 *ActualBufferSize) ; 



Params 


[in] 


Ctiannelldentifier 


[out] 


ActualBearerDescription 


[out] 


ActualBufferSize 


[out] 


RETURN 





Constant parameter set as defined below. 

The channel identifier that has been allocated by the ME. 

An array to which the actual bearer description allocated by the ME 

will be written. 

The actual buffer size allocated by the ME. 

The GeneralResult code of the OPEN CHANNEL proactive 

command. 



CatOpenGPRSChannel and CatOpenGPRSChannelEx issue the proactive command OPEN CHANNEL related to a 
GPRS bearer. The terminal response is parsed and if the command was successful the BearerDescription, BufferSize 
and Channelldentifier parameters are updated. 

The type CatOpenGPRSChannelExParams is defined as follows: 

typedef struct 

{ 

// Mandatory fields 

GsmOpenChannelOptions Options; 

BYTE AddressLength; 

const BYTE *Address; 

BYTE BearerDescription [8] ; 

UINT16 BufferSize; 

// Optional fields 

CatAlphaString UserConf irmationMessage.- 
Catlconldentif ier UserConf irmationlconldentif ier; 

BYTE AccessPointNameLength; 

const BYTE *AccessPointName; 

CatAddressType LocalAddress; 

CAT_ME_InterfaceTransportLevelType CAT_ME_Interf aceTransportLevel; 

CatAddressType DataDestinationAddress ; 
} GsmOpenGPRSChannelExParams; 

With the following members: 
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Options 

AddressLength 
Address 

BearerDescription 
BufferSize 



UserConfirmationMessage 



UserConfirmationlconldentifier 

AccessPointNameLength 

AccessPointName 

LocalAddress 

CA T_ME_lnterfaceTransportLevel 

DataDestinationAddress 



Acceptable values for this parameter are listed in 
CatOpenChannelOptions . This field is mandatory. 
Length in bytes of Address. This field is mandatory. 

The address to call. This field Is mandatory. 
The desired bearer. This field Is mandatory. 
The desired buffer size. This field is mandatory. 

String to display during the user confirmation phase; see CatAlphaStrinq . 
If this parameter is null, no user confirmation message TLV is passed to 
the IVIE. If UserConfirmationlVlessage is not null but 
UserConfirmationMessageLength is zero, a user confirmation message 
TLV is passed to the ME with the length component set to zero. 

The icon to display during the user confirmation phase. If the 

Uselcon member of this structure is zero, no user confirmation icon 

TLV is sent to the ME. 

The length in bytes of AccessPoint. 

The Access Point Name. 

See CatAddressType . 

See CAT MEInterfaceTransportLevelType . 

See CatAddressType. 



5.10.13 CatCloseChannel 

CatGeneralResult 

CatCloseChannel (CatDevice Channelldentifier, 

BYTE TitleLength, const void * Title, 
const Catlconldentif ier * Iconldentifier) ; 



Channelldentifier 

TitleLength 

Title 

Iconldentifier 

RETURN 



[In] The channel identifier as returned from one of the open commands 

[in] The length in bytes of Title. 

[In] String to display while ME is closing the channel. 

Optional icon identifier; see Catlconldentifier for member details. If 
[In] Icon Identifier \s NULL or if lconldentifier.Use\cor\ is zero, no Icon identifier is 

sent to the ME. 

The GeneralResult code of the CLOSE CHANNEL proactive command. 



CatCloseChannel issues a CLOSE CHANNEL proactive command that closes an open channeL 

5.10.14 CatReceiveData 

CatGeneralResult 

CatReceiveData (CatDevice Channelldentifier, 

BYTE TitleLength, const void * Title, 

BYTE ReguestedChannelDataLength, 

const Catlconldentifier * Iconldentifier , 

BYTE *ChannelData, 

BYTE *NumChannelBytesRead, 

BYTE *Nui:nChannelBytesLeft) ; 



Channelldentifier [in] 

TitleLength [in] 

Title [in] 

ReguestedChannelDataLength [in] 

Iconldentifier [in] 

ChannelData [out] 

NumChannelBytesRead [out] 

NumChannelBytesLeft [out] 

RETURN 



The channel identifier as returned from one of the open commands 

The length in bytes of Title. 

String to display while ME is receiving data. 

The number of bytes requested to be read. 

Optional icon identifier; see Catlconldentifier for member details. 

Iconldentifier \s NULL or if lconldentifier.\Jse\cor\ is zero, no icon 

identifier Is sent to the ME. 

Received channel data. 

The number of bytes received as channel data. 
The number of bytes remaining to be read from the channel buffer, 
255 if there are more than 255 bytes left to be read. 
The GeneralResult code of the RECEIVE DATA proactive command 



If 



or 



ETSI 



3GPP TS 31 .1 31 version 1 1 .0.0 Release 1 1 40 ETSI TS 1 31 1 31 V1 1 .0.0 (201 2-1 1 ) 

CatReceiveData issues a RECEIVE DATA proactive command that receives data from an open channel. The terminal 
response is parsed and if the command is successful the received data is copied into the ChannelData array and the 
NumChannelBytesRead and NumChannelBytesLeft parameters are updated. 

5.10.15 CatSendData 

CatGeneralResult 

CatSendData (CatDevice Channelldentifier, 

CatSendDataOptlons Options, 

BYTE TitleLength, const void *TitIe, 

BYTE ChannelDataLength, 

const void *ChannelData, 

const Catlconldentif ier * Iconldentifier, 

BYTE *ActualBytesSent) ; 



Options [in] 



Channelldentifier [in] The cliannel identifier as returned from one of the open commands 

TitleLength [in] The length in bytes of Title. 

Title [in] String to display while ME is receiving data. 

Specifies who packs the message. Acceptable values for this 

parameter are listed in CatSendDataOptlons . 
ChannelDataLength [in] The number of bytes to be sent from ChannelData. 

ChannelData [in] The data to be sent. 

Optional icon identifier; see Catlconldentifier for member details. If 
Iconldentifier [in] Iconldentifier \s NULL or if Iconldentifier Uselcon is zero, no icon 

identifier is sent to the IVIE. 
A t iR f Q t r ti The number of bytes sent (derived from the CHANNEL DATA 

Actuaiayiesbem [outj length TLV in the TERMINAL RESPONSE). 

RETURN The GeneralResult code of the SEND DATA proactive command. 



CatSendData issues the proactive command SEND DATA that sends data to an open channel. 

5.10.16 CatGetChannelStatus 

CatGeneralResult 

CatGetChannelStatus (CatDevice Channelldentifier, void * ChannelStatus) ; 



Channelldentifier [in] The channel identifier. 

ChannelStatus [out] Returned channel status bytes. 

Dc-r;/DA; The GeneralRcsult codo of the GET CHANNEL STATUS proactive 

command. 



CatGetChannelStatus issues a proactive command GET CHANNEL STATUS. The terminal response is parsed if the 
command is successful to find the status of the supplied channel. 

5.10.17 CatServiceSearch 

CatGeneralResult 

CatServiceSearch (CatBearer Bearerld, 

BYTE AttributeLength, void *Attributes, 

void *ServiceAvailability) ; 



Bearerld [in] The identifier of the bearer whose services will be searched. 

AttributeLength [in] The length of the following attribute array. 

Attrihutp'i \' 1 Attributes that describe bearer services, typically in a bearer specific 



ServiceAvailability [in] 



format. 

List of services offered by the bearer that satisfy the attributes, 

typically in a bearer specific format. 



CatServiceSearch searches for a particular service on a bearer. 
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5.10.18 CatGetServicelnformation 

CatGeneralResult 

CatGetServicelnformation (BYTE TitleLength, const BYTE * Title, 

const catlconldentif ier * Iconldentifier, 

CatBearer Bearerld, 

BYTE *AttributeLength, void ^Attributes, 

void *ServiceInformation) ; 



TitleLength 
Title 

Iconldentifier 

Bearerld 
AttributeLength 
Attributes 
Servicelnformation 



[in] The length in bytes of Title. 

[in] String to display acquiring service information. 

Optional icon identifier; see Catlconldentifier for member details, 
[in] Iconldentifier is NULL or if Icon Identifier Uselcon is zero, no icon 

identifier is sent to the IVIE. 
[in] The identifier of the bearer whose service information is requested, 
[in] The number of bytes in the following attribute array. 

[in] Attributes describing the service information requested, 
[out] The requested information. 



CatGetServicelnformation retrieves information about a particular service on a bearer. 

5.10.19 CatDeclareService 

CatGeneralResult 

CatDeclareService (CatBearer Bearerld, BYTE Serviceld, 

CatTransportProtocol Transport Protocol , 

WORD * PortNumber , 

BYTE ServiceRecordLength, 

void * ServiceRecord) ; 



Bearerld 

TransportProtocol 

PortNumber 

ServiceRecordLength 

ServiceRecord 



[in] The identifier of the bearer for which this service is being offered. 

[in] The transport protocol on which the service is provided. 

[in] The port on which the service is provided. 

[in] The number of bytes in the following service record. 

[in] The service record describing the service. 



CatDeclareService describes a new service. 



5.10.20 CatRunATCommand 

CatGeneralResult 

CatRunATConmand (BYTE TitleLength, const void * Title, 

BYTE CommandLength, const void * Command, 
const Catlconldentifier * Iconldentifier , 
void *Response, BYTE * ResponseLength) ; 



TitleLength 


[in] 


Length in bytes of Title. 


Title 


[in] 


String to display on ME while command is executing. 


CommandLength 


[in] 


Length in bytes of Command. 


Command 


[in] 


AT command string 

Optional icon identifier; see Catlconldentifier for member details. If 


Iconldentifier 


[in] 


Iconldentifier \s NULL or if IconldentifierUselcon is zero, no icon identifier is 
sent to the ME. 


Response 


[out] 


ME response string. 


ResponseLength 


[out] 


Length in bytes of ME response string. 


RETURN 




The GeneralResult code of the RUN A T COMMAND proactive 
command. 



CatRunATCommand issues the proactive command RUN AT COMMAND that sends an AT command to the ME. The 
terminal response is parsed and if successful the parameters Response and ResponseLength are updated. 
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5.10.21 CatSendDTMFCommand 

CatGeneralResult 

CatSendDTMFConnnand (BYTE TitleLength, const void * Title, 

BYTE DTMFCodeLength, const void *DTMFCode, 

const Catlconldentif ier * Iconldentifier) ; 



TitleLength 


[in] 


The length in bytes of Title. 


Title 


[in] 


Title displayed while the DTMF string is sent to the network. 


DTMFCodeLength 


[in] 


The length in bytes of DTMFCode. 


DTMFCode 


[in] 


DTMF string sent to the network. 

Optional icon identifier; see Catlconldentifier for member details. If 


Iconldentifier 


[in] 


Iconldentifier is NULL or if Iconldentifier.Uselcon is zero, no icon 
identifier is sent to the IVIE. 


RETURN 




The GeneralResult code of the SEND DTMF COMMAND proactive 

command. 



CatSendDTMF issues the proactive command SEND DTMF COMMAND that sends a dual tone multiple frequency 
(DTMF) string to the network. 

5.1 1 Supporting Data Types 

typedef unsigned char BYTE, 
typedef unsigned short WORD, 
typedef unsigned long int DWORD. 

5.11.1 CatRecordAccessMode 



pedef enum 


{ 






NEXT 






= 0x02, 


PREVIOUS 






= 0x03, 


CURRENT 






= 0x04, 


ABSOLUTE 






= 0x04 


CatRecordAc 


ces 


sMode ; 





5.11.2 CatSearchMode 

typedef enum { 
BEGINNING_FORWARD , 
END_BACKWARD , 
NEXT_FORWARD , 
PREVIOUS_BACKWARD 
} CatSearchMode; 

5.1 1 .3 CatFrameworkEventType 

typedef enum 

{ 

// Command monitoring events 
EVENT_TERMINAL_PROFILE_COMMAND , 
EVENT_STATUS_COMMAND 
EVENT_ENVELOPE_COMMAND , 

// Application lifecycle events start here 
EVENT_APPLICATION_LIFECYCLE_INSTALL = 0x20 
// Framework fabricated events start here 
EVENT_UPDATE_EF_SMS = 0x4 
EVENT_PROFILE_DOWNLOAD , 
EVENT_FORMATTED_SMS_PP_UPD , 
EVENT_STATUS_COMMAND , 
EVENT_UNFORMATTED_SMS_PP_UPD , 
EVENT_MENU_SELECTION, 
EVENT_FORMATTED_SMS_PP_ENV , 
EVENT_UNFORMATTED_SMS_PP_ENV , 
EVENT_FORMATTED_SMS_PP_CB , 
EVENT MENU SELECTION HELP REQUEST, 
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EVENT_CALL_CONTROL_BY_S IM , 
EVENT_MO_SHORT_MESSAGE_CONTROL_BY_SIM, 
EVENT_TIMER_EXPIRATION, 
EVENT_DOWNLOAD_MT_CALL_EVENT , 
EVENT_DOWNLOAD_CALL_CONNECTED_EVENT, 
EVENT_DOWNLOAD_CALL_DISCONNECTED_EVENT, 
EVENT_DOWNLOAD_LOCATION_STATUS_EVENT, 
EVENT_DOWNLOAD_USER_ACTIVITY_EVENT, 
EVENT_DOWNLOAD_IDLE_SCREEN_AVAILABLE_EVENT, 
EVENT_DOWNLOAD_CARD_READER_STATUS_EVENT, 
EVENT_DOWNLOAD_LANGUAGE_SELECTION_EVENT, 
EVENT_DOWNLOAD_BROWSER_TERMINATION_EVENT, 
EVENT_DOWNLOAD_DATA_AVAILABLE_EVENT, 
EVENT_DOWNLOAD_CHANNEL_STATUS_EVENT, 
EVENT_UNRECOGNIZED_ENVELOPE , 
EVENT_TERMINAL_RESPONSE , 
EVENT_APPLICATION_INSTALL 
} CatFrameworkEventType; 

5. 11 .4 CatEnvelopeTagType 

typedef enum { 

SMS_PP_DOWNLOAD_TAG = OxDl , 

CELL_BROADCAST_TAG = 0xD2 , 

MENU_SELECTION_TAG = 0xD3 , 

CALL_CONTROL_TAG = OxD4 , 
MO_SHORT_MESSAGE_CONTROL_TAG = OxD5 , 

EVENT_DOWNLOAD_TAG = 0xD6 , 

TIMER_EXPIRATION = OxD7 

} CatEnvelopeTagType; 



5.11.5 CatEventType 



typedef enum { 
MT_CALL_EVENT 
CALL_CONNECTED_EVENT 
CALL_DISCONNECTED_EVENT 
LO C AT I ON_S TATUS_E VENT 
USER_ACTIVITY_EVENT 
IDLE_SCREEN_AVAILABLE 
CARD_READER_STATUS 
LANGUAGE_SELECTION 
BROWSER_TERMINATION 
DATA_AVAILABLE 
CHANNEL_STATUS 

} CatEventType ; 



0x00, 
0x01, 
0x02, 
0x03, 
0x04, 
0x05, 
0x06, 
0x07, 
0x08, 
0x09, 
OxOA 



5.11.6 CatTextString 



typedef struct 

{ 

CatDCSValue DCSValue; 

BYTE TextStringLength; 

const void *TextString; 
} CatTextString; 



5.11.7 CatAlphaString 

typedef struct 

{ 

BYTE AlphaStringLength; 

const void *AlphaString; 
} CatTextString; 



5.11.8 Catlconldentifier 

typedef struct 

{ 

BYTE Us el con; 

BYTE Iconldentif ier; 

BYTE IconOptions; 
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} Catlconldentif ier; 

The Catlconldentifier structure is defined as follows: 



If zero, the icon identifier is not used in the proactive command. If non- 
Uselcon zero, the Iconldentifier and IconOption members are used in the 

proactive command. 
Iconldentifier Index of the icon to display. 

Options with which to display the icon selected from CatlconOption . 

This is specified as a BYTE rather than CatlconOptios as, in C, an 
IconOptions enumeration uses the same storage as an int which is at least 16 bits, 

whereas the proactive commands that use these identifiers use 8-bit 
quantities. 



5.11.9 CatlconOption 

typedef enum 

{ 

SHOW_WITHOUT_TEXT = 0x0 0, 
SHOW_WITH_TEXT = 0x01 

} CatlconOption; 

5.11.10 CatDCSValue 

typedef enum 

{ 

DCS_SMS_PACKED = 0x0 0, 
DCS_SMS_UNPACKED = 0x04, 
DCS_SMS_UNICODE = 0x08 

} CatDCSValue ; 



5.11.11 CatDisplayTextOptions 

typedef enum 

{ 

NORMAL_PRIORITY_AUTO_CLEAR = 0x0 0, 

NORMAL_PRIORITY_USER_CLEAR = 0x8 0, 

HIGH_PRIORITY_AUTO_CLEAR = 0x01, 

HIGH_PRIORITY_USER_CLEAR = 0x81 

} CatDisplayTextOptions; 



5.11.12 CatGetlnKeyOptions 

typedef enum 

{ 

YES_NO_OPTION_NO_HELP = 0x04, 

YES_NO_OPTION_WITH_HELP = 0x84, 

DIGITS_ONLY_NO_HELP = 0x00, 

DIGITS_ONLY_WITH_HELP = 0x80, 

SMS_CHARACTER_NO_HELP = 0x01, 

SMS_CHARACTER_WITH_HELP = 0x81, 

UCS2_CHARACTER_N0_HELP = 0x03, 

UCS2_CHARACTER_WITH_HELP = 0x8 3 

} CatGetlnKeyOptions; 



5.11.13 CatGetlnputOptions 

typedef enum 

{ 

PACKED_DIGITS_ONLY_NO_HELP = 0x08, 

PACKED_DIGITS_ONLY_WITH_HELP = 0x88, 

PACKED_DIGITS_ONLY_NO_ECHO_NO_HELP = OxOC, 

PACKED_DIGITS_ONLY_NO_ECHO_WITH_HELP = 0x8C, 

UNPACKED_DIGITS_ONLY_NO_HELP = 0x0 0, 

UNPACKED_DIGITS_ONLY_WITH_HELP = 0x80, 

UNPACKED_DIGITS_ONLY_NO_ECHO_NO_HELP = 0x04, 

UNPACKED_DIGITS_ONLY_NO_ECHO_WITH_HELP = 0x84, 

PACKED SMS ALPHABET NO HELP = 0x0 9, 
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PACKED_SMS_ALPHABET_WITH_HELP = 0x89, 

PACKED_SMS_ALPHABET_NO_ECHO_NO_HELP = OxOD, 

PACKED_SMS_ALPHABET_NO_ECHO_HELP = 0x8D, 

UNPACKED_SMS_ALPHABET_NO_HELP = 0x01, 

UNPACKED_SMS_ALPHABET_WITH_HELP = 0x81, 

UNPACKED_SMS_ALPHABET_NO_ECHO_NO_HELP = 0x05, 

UNPACKED_SMS_ALPHABET_NO_ECHO_WITH_HELP = 0x85, 

UCS2_ALPHABET_N0_HELP = 0x03, 

UCS2_ALPHABET_WITH_HELP = 0x83, 

UCS2_ALPHABET_N0_ECH0_N0_HELP = 0x07, 

UCS2_ALPHABET_N0_ECH0_WITH_HELP = 0x87 
CatGetlnputOptions ; 



5.11.14 CatSelectltemOptions 



typedef enum 



PRESENT_AS_DATA_VALUES_NO_HELP 
PRESENT_AS_DATA_VALUES_WITH_HELP 
PRESENT_AS_NAVIGATION_OPTIONS_NO_HELP 
PRESENT_AS_NAVIGATION_OPTIONS_WITH_HELP 
DEFAULT_STYLE_NO_HELP 
DEFAULT_STYLE_WITH_HELP 
} CatSelectltemOptions ; 



0x01, 
0x81, 
0x03, 
0x83, 
0x00, 
0x80 



5.11.15 CatTimeUnit 

typedef enum 

{ 

GSM_MINUTES = 0x0 0, 

GSM_SECONDS = 0x01, 

GSM_TENTHS_OF_SECONDS = 0x02 

} CatTimeUnit; 



5.11.16 CatTone 



typedef enum 



DIAL_TONE 

CALLER_BUSY 

CONGESTION 

RADIO_PATH_ACKNOWLEDGE 

CALL_DROPPED 

SPECIAL_INFORiyLATION_OR_ERROR 

CALL_WAITING_TONE 

RINGING_TONE 

GENERAL_BEEP 

POSITIVE_ACKNOWLEDGE_TONE 

NEGATIVE_ACKNOWLEDGE_TONE 

CatTone ; 



0x01, 
0x02, 
0x03, 
0x04, 
0x05, 
0x06, 
0x07, 
0x08, 
0x10, 
0x11, 
0x12 



5.11.17 CatRef reshOptions 

typedef enum 

{ 

REFRESH_SIM_INIT_AND_FULL_FILE_CHANGE_NOTIFICATION = 0x00, 

REFRESH_FILE_CHANGE_NOTIFICATION = 0x01, 

REFRESH_SIM_INIT_AND_FILE_CHANGE_NOTIFICATION = 0x02, 

REFRESH_SIM_INIT = 0x03, 

REFRESH_SIM_RESET = 0x04 

} CatRef reshOptions; 



5.11.18 CatGetReaderStatusOptions 

typedef enum 

{ 

CARD_READER_STATUS = 0x0 0, 

CARD_READER_IDENTIFIER = 0x01 
} CatGetReaderStatusOptions; 
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5.11.19 CatDevice 



typedef enum 






1 

DEVICE_ 


KEPYAD 




= 0x01 


DEVICE_ 


DISPLAY 




= 0x02 


DEVICE_ 


EARPIECE 




= 0x03 


DEVICE_ 


_CARD_READER_ 





= 0x10 


DEVICE 


CARD READER 


1 


= 0x11 


DEVICE^ 


_CARD_READER_ 


2 


= 0x12 


DEVICE_ 


_CARD_READER_ 


3 


= 0x13 


DEVICE_ 


_CARD_READER_ 


4 


= 0x14 


DEVICE_ 


_CARD_READER_ 


5 


= 0x15 


DEVICE_ 


_CARD_READER_ 


> 


= 0x16 


DEVICE_ 


_CARD_READER_ 


7 


= 0x17 


DEVICE_ 


_CHANNEL_1 




= 0x21 


DEVICE 


CHANNEL 2 




= 0x22 


DEVICE^ 


_CHANNEL_3 




= 0x2 3 


DEVICE_ 


_CHANNEL_4 




= 0x24 


DEVICE_ 


_CHANNEL_5 




= 0x2 5 


DEVICE_ 


_CHANNEL_6 




= 0x2 S 


DEVICE_ 


_CHANNEL_7 




= 0x2 7 


DEVICE_ 


SIM 




= 0x81 


DEVICE_ 


_ME 




= 0x82 


DEVICE_ 


NETWORK 




= 0x83 


} CatDevice; 







5.11.20 CatGeneralResult 



typedef enum 

{ 

CAT_COMMAND_SUCCESSFUL = 0x0 

CAT_COMMAND_SUCCESSFUL_WITH_PARTIAL_COMPREHENSION = 0x01 

CAT_COMiyLAND_SUCCESSFUL_WITH_MISSING_INFORMATION = 0x02 

CAT_REFRESH_SUCCESSFUL_WITH_ADDITIONAL_EFS_READ = 0x0 3 

CAT_COMMAND_SUCCESSFUL_BUT_ICON_NOT_FOUND = 0x04 

CAT_COMMAND_SUCCESSFUL_BUT_MODIFIED_BY_CALL_CONTROL = 0x05 

CAT_COMiyLAND_SUCCESSFUL_BUT_LIMITED_SERVICE = 0x06 

CAT_COMMAND_SUCCESSFUL_WITH_MODIFICATION = 0x07 

CAT_ABORTED_BY_USER = 0x10 

CAT_BACKWARD = 0x11 

CAT_NO_RESPONSE = 0x12 

CAT_HELP_REQUIRED = 0x13 

CAT_USSD_ABORTED_BY_USER = 0x14 

CAT_ME_UNABLE_TO_PROCESS_COMMAND = 0x2 

CAT_NETWORK_UNABLE_TO_PROCESS_COMMAND = 0x21 

CAT_USER_REJECTED_SETUP_CALL = 0x22 

CAT_USER_CLEARED_BEFORE_RELEASE = 0x2 3 

CAT_ACTION_CONTRADICT_TIMER_STATE = 0x24 

CAT_TEMP_PROBLEM_IN_CALL_CONTROL = 0x2 5 

CAT_LAUNCH_BROWSER_ERROR = 0x2 6 

CAT_COMMAND_BEYOND_ME_CAPABILITIES = 0x30 

CAT_COMMAND_TYPE_NOT_UNDERSTOOD = 0x31 

CAT_COMiyLAND_DATA_NOT_UNDERSTOOD = 0x32 

CAT_COMMAND_NUMBER_NOT_KNOWN = 0x3 3 

CAT_SS_RETURN_ERROR = 0x34 

CAT_SMS_RP_ERROR = 0x3 5 

CAT_REQUIRED_VALUES_MISSING = 0x36 

CAT_USSD_RETURN_ERROR = 0x3 7 

CAT_MULTIPLE_CARD_COMMAND_ERROR = 0x3 8 

CAT_PERMANENT_PROBLEM_IN_SMS_OR_CALL_CONTROL = 0x3 9 

CAT_BEARER_INDEPENDENT_PROTOCOL_ERROR = 0x3A 

} CatGeneralResult ; 
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5.11.21 CatTimerValue 

typedef struct 

{ 

BYTE hour; 

BYTE minute; 

BYTE second; 
} CatTimerValue; 

The CatTimerValue data type has three one-byte values: 



tiour 

Minute 

Second 


Hours part of timer. 
Minutes part of timer. 
Seconds part of timer. 



5.11.22 CatTimelnterval 



typedef struct 

{ 

BYTE timeUnit; 

BYTE timelnterval; 
1 CatTimelnterval; 



The CatTimlnterval data type has two one-byte values: 



One of the CatTimeUnit enumeration values. This is specified as a BYTE rather than CatTimeUnit 
timeUnit as, in C, an enumeration uses the same storage as an int which is at least 16 bits, whereas the 

proactive commands that use these identifiers use 8-bit quantities. 
Timelntervai The number of timeUnits. 



5.11.23 CatFileStatus 



typedef struct 



WORD recordLength; 
WORD numberOf Records ; 
BYTE lengthOfTrailer; 
BYTE trailer [] ; 
CatEFStatus; 



typedef struct 
{ 



BYTE numberOf DFs; 
BYTE numberofEFs; 

BYTE CHVlStatuS; 

BYTE unblockCHVlStatus; 

BYTE CHV2Status; 

BYTE unblockCHV2Status; 

BYTE lengthOfTrailer; 
BYTE trailer [] ; 
} CatDFStatus; 

typedef struct 
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DWORD totalFileSize; 

UINT16 filelD; 

BYTE f ileDescriptorByte; 

BYTE fileType; // 00=RFU, 

BYTE fileLifeCycleStatus; 

union 



01=MF, 02=DF, 04=EF 



CatEFStatus ef; 
CatDFStatus df ; 
} u; 
} CatFileStatus; 



5.1 1 .24 CatLanguageNotificationOptions 

typedef enum 

{ 

LANGUAGE_NON_SPECIFIC_NOTIFICATION = 0x00, 
LANGUAGE_SPECIFIC_NOTIFICATION = 0x01 

} CatLanguageNotificationOptions ; 



5.1 1 .25 CatLocation Information 

typedef struct 

{ 

BYTE mobileCountryNetworkCodes [3] ; 

BYTE LAC [2] ; 

BYTE celllD [2] ; 
} CatLocationInf ormation; 



5.1 1 .26 CatTiming Advance 

typedef struct 

{ 

BYTE MEStatus; 

BYTE timingAdvance; 
} CatTimingAdvance; 

5.1 1 .27 CatLaunchBrowserOptions 

typedef enum 

{ 

LAUNCH_BROWSER_IF_NOT_ALREADY_LAUNCHED = 0x00, 

USE_EXISTING_BROWSER = 0x02, 

CLOSE_EXISTING_BROWSER_AND_LAUNCH_NEW_BROWSER = 0x03 

} CatLaunchBrowserOptions; 

5.1 1 .28 CatSetupCallOptions 

typedef enum 

{ 

CALL_ONLY_IF_NOT_BUSY = 0x00, 

CALL_ONLY_IF_NOT_BUSY_WITH_REDIAL = 0x01, 

CALL_AND_PUT_ALL_OTHER_CALLS_ON_HOLD = 0x02, 

CALL_AND_PUT_ALL_OTHER_CALLS_ON_HOLD_WITH_REDIAL = 0x0 3, 

CALL_AND_DISCONNECT_ALL_OTHER_CALLS = 0x04, 

CALL_AND_DISCONNECT_ALL_OTHER_CALLS_WITH_REDIAL = 0x05 

} CatSetupCallOptions; 
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5.1 1 .29 CatTypeOfNumberAndNumberingPlanldentifier 

typedef enum 

{ 

TON_UNKNOWN_AND_NPI_UNKNOWN = 0x8 

TON_INTERNATIONAL_AND_NPI_UNKNOWN = 0x9 

TON_NATIONAL_AND_NPI_UNKNOWN = OxAO 

TON_NETWORK_AND_NPI_UNKNOWN = OxBO 

TON_SUBSCRIBER_AND_NPI_UNKNOWN = OxCO 

TON_UNKNOWN_AND_NPI_TELEPHONE = 0x81 

TON_INTERNATIONAL_AND_NPI_TELEPHONE = 0x91 

TON_NATIONAL_AND_NPI_TELEPHONE = OxAl 

TON_NETWORK_AND_NPI_TELEPHONE = OxBl 

TON_SUBSCRIBER_AND_NPI_TELEPHONE = OxCl 

TON_UNKNOWN_AND_NPI_DATA = 0x8 3 

TON_INTERNATIONAL_AND_NPI_DATA = 0x93 

TON_NATIONAL_AND_NPI_DATA = 0xA3 

TON_NETWORK_AND_NPI_DATA = 0xB3 

TON_SUBSCRIBER_AND_NPI_DATA = 0xC3 

TON_UNKNOWN_AND_NPI_TELEX = 0x84 

TON_INTERNATIONAL_AND_NPI_TELEX = 0x94 

TON_NATIONAL_AND_NPI_TELEX = OxA4 

TON_NETWORK_AND_NPI_TELEX = OxB4 

TON_SUBSCRIBER_AND_NPI_TELEX = OxC4 

TON_UNKNOWN_AND_NPI_NATIONAL = 0x8 8 

TON_INTERNATIONAL_AND_NPI_NATIONAL = 0x98 

TON_NATIONAL_AND_NPI_NATIONAL = 0xA8 

TON_NETWORK_AND_NPI_NATIONAL = 0xB8 

TON_SUBSCRIBER_AND_NPI_NATIONAL = 0xC8 

TON_UNiaSIOWN_AND_NPI_PRIVATE = 0x8 9 

TON_INTERNATIONAL_AND_NPI_PRIVATE = 0x99 

TON_NATIONAL_AND_NPI_PRIVATE = OxA9 

TON_NETWORK_AND_NPI_PRIVATE = 0xB9 

TON_SUBSCRIBER_AND_NPI_PRIVATE = OxC9 

TON_UNKNOWN_AND_NPI_ERMES = 0x8A 

TON_INTERNATIONAL_AND_NPI_ERMES = Ox9A 

TON_NATIONAL_AND_NPI_ERMES = OxAA 

TON_NETWORK_AND_NPI_ERMES = OxBA 

TON_SUBSCRIBER_AND_NPI_ERMES = OxCA 
} CatTypeOfNumberAndNumberingPlanldentif ier; 

5.1 1 .30 CatSendShortMessageOptions 

typedef enum 

{ 

PACKING_NOT_REQUIRED = 0x0 0, 

PACKING_BY_THE_ME_REQUIRED = 0x01 
} CatSendShortMessageOptions; 

5.1 1 .31 CatSendDataOptions 

typedef enum 

{ 

STORE_DATA_IN_TX_BUFFER = 0x0 0, 

SEND_DATA_IMMEDIATELY = 0x01 
} CatSendDataOptions ; 
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5.1 1 .32 CatMEInterfaceTransportLevelType 



typedef struct 



UDP = 0x01, 
TCP = 0x02 
} TransportProtocolType; 
UINT16 CAT_ME_PortNumber; 
} CAT_MEInterf aceTransportLevelType ; 



5.11.33 CatBearer 



typedef enum 



{ 



BEARER_SMS = 0x0 0, 
BEARER_CSD = 0x01, 
BEARER_USSD = 0x02, 
BEARER_GPRS = 0x03 
} CatBearer; 



5.1 1 .34 CatOpenChannelOptions 

typedef enum 

{ 

ON_DEMAND_LINK_ESTABLISHMENT = 0x00, 
IMMEDIATE_LINK_ESTABLISHMENT = 0x01 

} CatOpenChannelOptions; 



5.11.35 CatAddressType 

typedef struct 



IPV4 = 0x21, 

IPV6 = 0x97 
} AddressType; 
BYTE AddressLength; 
const void *Address; 
} CatAddressType; 



5.11.36 CatFID 



#define FID_DF_GRAPHICS Ox5F5 
#define FID_DF_TELECOM OxVFlO 
#define FID_EF_ADN 0x6F3A 
#define FID_EF_ARR 0x2F06 
#define FID_EF_BDN 0x6F4D 
#define FID_EF_CCP 0x6F3D 
#define FID_EF_DIR 0x2F00 
idefine FID_EF_EXT1 0x6F4A 
#define FID_EF_EXT2 0x6F4B 
idefine FID_EF_EXT3 0x6F4C 
#define FID_EF_EXT4 0x6F4E 
idefine FID_EF_FDN 0x6F3B 
idefine FID_EF_ICCID 0x2FE2 
idefine FID_EF_IMG 0x4F20 
idefine FID_EF_LND 0x6F44 
idefine FID_EF_MSISDN OxSF40 
idefine FID_EF_PL 0x2F05 
idefine FID_EF_SDN 0x6F49 
#define FID_EF_SMS 0x6F3C 
#define FID_EF_SMSP 0x6F42 
#define FID_EF_SMSR 0x6F47 
#define FID EF SMSS Ox6F43 
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5.11.37 CatTextFormat 



#define 


TEXT_ 


_FORMAT_ 


LEFT 


#define 


TEXT_ 


_FORMAT_ 


CENTER 


#define 


TEXT_ 


_FORMAT_ 


RIGHT 


#def ine 


TEXT_ 


_FORiyiAT_ 


_L ANGUAGE_D EPENDENT 


#def ine 


TEXT_ 


_FORMAT_ 


_NORMAL_SIZE 


#def ine 


TEXT_ 


_FORMAT_ 


_LARGE_SIZE 


#def ine 


TEXT 


FORMAT 


SMALL SIZE 


#define 


text| 


FORMAT^ 


BOLD 


#define 


TEXT_ 


_FORMAT_ 


ITALIC 


#define 


TEXT_ 


_FORMAT_ 


UNDERLINED 


#define 


TEXT 


FORMAT 


STRIKETHROUGH 



0x00 
0x01 
0x02 
0x03 
0x00 
0x04 
0x08 
0x10 
0x2 
0x4 
0x80 



5.1 1 .38 CatTextForegroundColour 



typedef enum { 






BLACK 


= 


0x00 


DARK_GREY 


= 


0x01 


DARK_RED 


= 


0x02 


DARK_YELLOW 


= 


0x03 


DARK_GREEN 


= 


0x04 


DARK_CYAN 


= 


0x05 


DARK_BLUE 


= 


0x06 


DARK_MAGENTA 


= 


0x07 


GREY 


= 


0x08 


WHITE 


= 


0x09 


BRIGHT^RED 


= 


OxOA 


BRIGHT_YELLOW 


= 


OxOB 


BRIGHT_GREEN 


= 


OxOC 


BRIGHT_CYAN 


= 


OxOD 


BRIGHT_BLUE 


= 


OxOE 


BRIGHT_MAGENTA 


= 


OxOF 


} CatTextForegroundColour ; 







5.1 1 .39 CatTextBackgroundColour 



typedef enum { 






BLACK 


= 


0x00 


DARK_GREY 


= 


0x10 


DARK_RED 


= 


0x2 


DARK_YELLOW 


= 


0x3 


DARK GREEN 


= 


0x4 


DARK_CYAN 


= 


0x50 


DARK_BLUE 


= 


OxSO 


DARK_MAGENTA 


= 


0x70 


GREY 


= 


0x80 


WHITE 


= 


0x90 


BRIGHT_RED 


= 


OxAO 


BRIGHT_YELLOW 


= 


OxBO 


BRIGHT_GREEN 


= 


OxCO 


BRIGHT_CYAN 


= 


OxDO 


BRIGHT_BLUE 


= 


OxEO 


BRIGHT_MAGENTA 


= 


OxFO 


} CatTextBackgroundColour; 
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Annex A (normative): 

Application executable architecture 



Name 


Value 


Meaning 


EM NONE 





No machine 


EM M32 


1 


AT&T WE 321 00 


EM SPARC 


2 


SPARC 


EM 386 


3 


Intel 80386 


EM 68K 


4 


Motorola 68000 


EM 88K 


5 


Motorola 88000 


RESERVED 


6 


Reserved for future use 


EM 860 


7 


Intel 80860 


EM MIPS 


8 


MIPS 1 Architecture 


EM S370 


9 


IBM System/370 Processor 


EM MIPS RS3 LE 


10 


MIPS RS3000 Little-endian 


RESERVED 


11-14 


Reserved for future use 


EM PARISC 


15 


Hewlett-Packard PA-RISC 


RESERVED 


16 


Reserved for future use 


EM VPP500 


17 


Fujitsu VPP500 


EM SPARC32PLUS 


18 


Enhanced instruction set SPARC 


EM 960 


19 


Intel 80960 


EM PPC 


20 


PowerPC 


EM PPC64 


21 


64-bit PowerPC 


RESERVED 


22-35 


Reserved for future use 


EM V800 


36 


NEC V800 


EM FR20 


37 


Fujitsu FR20 


EM RH32 


38 


TRW RH-32 


EM RCE 


39 


Motorola RCE 


EM ARM 


40 


Advanced RISC Machines ARM 


EM ALPHA 


41 


Digital Alpha 


EM SH 


42 


Hitachi SH 


EM SPARCV9 


43 


SPARC Version 9 


EM TRICORE 


44 


Infineon Tricore embedded processor 


EM ARC 


45 


Argonaut RISC Core 


EM H8 300 


46 


Hitachi H8/300 


EM H8 300H 


47 


Hitachi H8/300H 


EM H8S 


48 


Hitachi H8S 


EM H8 500 


49 


Hitachi H8/500 


EM lA 64 


50 


Intel IA-64 processor architecture 


EM MIPS X 


51 


Stanford MIPS-X 


EM COLDFIRE 


52 


Motorola ColdFire 


EM 68HC12 


53 


Motorola M68HC1 2 


EM MMA 


54 


Fujitsu MMA Multimedia Accelerator 


EM PCP 


55 


Siemens PCP 


EM NCPU 


56 


Sony nCPU embedded RISC processor 


EM NDR1 


57 


Dense NDR1 microprocessor 


EM STARCORE 


58 


Motorola Star*Core processor 


EM ME16 


59 


Toyota ME16 processor 


EM ST100 


60 


STMicroelectronics ST1 00 processor 


EM TINYJ 


61 


Advanced Logic Corp. TinyJ embedded processor family 


Reserved 


62-65 


Reserved for future use 


EM FX66 


66 


Infineon FX66 microcontroller 


EM ST9PLUS 


67 


STMicroelectronics ST9-i- 8/1 6 bit microcontroller 


EM ST7 


68 


STMicroelectronics ST7 8-bit microcontroller 


EM 68HC16 


69 


Motorola MC68HC16 Microcontroller 


EM 68HC11 


70 


Motorola MC68HC1 1 Microcontroller 


EM 68HC08 


71 


Motorola MC68HC08 Microcontroller 


EM 68HC05 


72 


Motorola MC68HC05 Microcontroller 


EM SVX 


73 


Silicon Graphics SVx 


EM ST19 


74 


STMicroelectronics ST19 8-bit microcontroller 


EM VAX 


75 


Digital VAX 


EM CRIS 


76 


Axis Communications 32-bit embedded processor 
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Name 


Value 


Meaning 


EM JAVELIN 


77 


Infineon Technologies 32-bit embedded processor 


EM FIREPATH 


78 


Element 14 64-bit DSP Processor 


EM ZSP 


79 


LSI Logic 16-bit DSP Processor 


EM MMIX 


80 


Donald Knuth's educational 64-bit processor 


EM HUANY 


81 


Harvard University machine-independent object files 


EM PRISM 


82 


SiTera Prism 


EM MEL 


83 


Multos Executable Language (MEL) byte codes 


EM RTE 


84 


Microsoft Smart Card for Windows Runtime Environment byte codes 
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Annex B (informative): 

Example 

/** 

** Example of Toolkit Application written for the C SIM API 
*/ 

#pragma AID AO 000000090001 

#include <stdlib.h> 
#include "application. h" 
#include "cat.h" 
#include "catlow.h" 

#define DF_GSM 0x7F20 
#define EF PUCT Ox6F41 



"MyMenu" ; 



"Hello, world"; 
= "Your name?" ; 



const BYTE SERVER_OPERATION = OxOF; 

const BYTE EXIT_REQUESTED_BY_USER = 0x10; 

static const char menuEntry[] = "Servicel"; 

static const char menuTitle [] 

static char iteml [] = "ITEMl"; 

static char item2 [] = "ITEM2"; 

static char item3 [] = "ITEM3"; 

static char item4 [] = "ITEM4"; 

static char textDText [] 

static char textGInput [] 

BYTE Itemldentif ier; 

static BYTE * byteptr; 

static void * bufptr; 

static BYTE buffer [10]; 

static BYTE itemid; 

static BYTE result; 

static BYTE repeat; 

void main (void) 

{ 

switch {CatGetFrameworkEvent { ) ) 

{ 

case EVENT_APPLICATION_LIFECYCLE_INSTALL : 
// Define the application Menu Entry and register to the EVENT_MENU_SELECTION 
CatSetMenuString {1, sizeof (menuEntry) , {const void *) MenuEntry,NULL, , 0) ; 
// register to the EVENT_UNFORMATTED_SMS_PP_ENV 
CatNotifyOnEnvelope {SMS_PP_DOWNLOAD_TAG, 1) ; 
break; 
case EVENT_ENVELOPE_COMMAND : 

{ 

BYTE length; 

switch {CatOpenEnvelope (Stlength) ) 

{ 

case MENU_SELECTION_TAG: 

// Prepare the Select Item proactive command 

// Append the Menu Title 

CatSelectltem {sizeof (MenuTitle) , 
{const void *) MenuTitle, 
DEFAULT_STYLE_NO_HELP) ; 

// add all the Item 

CatSelectAddItem{sizeof (iteml) 

CatSelectAddItem{sizeof {item2) 

CatSelectAddItem{sizeof {item3) 

CatSelectAddItem{sizeof {item4) 

// ask the CAT Toolkit Framework to send 
//the proactive command and check the result 

if { !CatEndSelectItem{&ItemId,NULL) ) 



{const void *) iteml, 1) 

{const void *)item2,2) 

{const void *)item3,3) 

{const void *)item4,4) 



{ 



switch {Itemid) 
{ 



case 1 
case 2 
case 3 



// DisplayText 



CatDisplayText {DCS_SMS_UNPACKED, 



{const void *) textDText, 



sizeof {textDText) 
NORMAL PRIORITY USER CLEAR, NULL, 0) ; 
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break; 
case 4 : // Ask the user to enter data and display it 
repeat =0 ; 
do 

{ 

if {CatGetlnput {DCS_SMS_UNPACKED, 
sizeof (textGInput) , 
{const void *) textGInput, 
UNPACKED_SMS_ALPHABET_NO_HELP , 
DCS_SMS_UNPACKED , , NULL , 
0, sizeof (buffer) , NULL, 
{CatDCSValue *)&result, 
Screpeat , 

{void *) buffer) ==EXIT_REQUESTED_BY_USER) 
break ; 
// display the entered text 
CatDisplayText {{CatDCSValue ) result, 
repeat, {const void *) buffer, 
NORMAL_PRIORITY_USER_CLEAR, NULL, 0) ; 
} while {repeat) ; 
} 
} 
break; 
case EVENT_UNFORMATTED_SMS_PP_ENV: 
CatOpenEnvelope {Stresult) ; 

byteptr= {BYTE * ) catGetData {1) ; /* go to numberlength */ 
result= {*byteptr) >>1; 
/* calculate numberlength, rounded up */ 
if { {*byteptr) Stl) result + +; 
catGetData {result+12) ; /* move to the beginning of the data */ 
// get the offset of the instruction in the TP-UD field 
CatGetData {SERVER_OPERATION) ; 
result=CatGetBYTE{) ; 

switch {result) 

{ 

case 0x41 : // Update of a gsm file 

bufptr=CatGetData{3) ; 
// write these data in the Efpuct 
CatSelect {FID_DF_GSM) ; 
CatSelect {FID_EF_PUCT) ; 
CatUpdateBinary {0, 3,bufptr) ; 
break; 
case 0x36 : // change the MenuTitle for the Selectltem 

bufptr=CatGetData {sizeof {menuTitle) ) ; 

memcpy{bufptr,memuTitle, sizeof {menuTitle) ) ; 



break; 
default: 

CatExit {) ; 
break; 

} 
CatExit { ) ; 
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Annex C (informative): 
Change history 



Change history 


Date 


TSG# 


TSG Doc 


CR 


Re 

V 


Cat 


Subject/Comment 


Old 


New 


2003-03 


TP-19 


TP-030023 


001 




D 


Editorial Corrrections 


6.0.0 


6.1.0 


2007-06 


- 


- 


- 


- 


- 


Update to Rel-7 version (IVICC) 


6.1.0 


7.0.0 


2009-03 


- 


- 


- 


- 


- 


Update to Rel-8 version (IVICC) 


7.1.0 


8.0.0 


2009-12 


CT-46 


CP-091011 


002 


1 


F 


References update 


8.0.0 


8.1.0 


2009-12 


CT-46 


- 


- 


- 


- 


Upgrade of tfie specification to Rel-9 


8.1.0 


9.0.0 


2011-03 


SP-51 


- 


- 


- 


- 


Upgrade of tfie specification to Rel-10 


9.0.0 


10.0.0 


2012-09 


SP-57 






- 


- 


Upgrade of tfie specification to Rel-1 1 


10.0.0 


11.0.0 
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